current-time — remote MCP server

current-time — remote MCP server

A small, hardened remote MCP server exposing date/time tools over theStreamable HTTP transport, so it can be registered as a custom connector inClaude.ai or used by any MCP client.

Most time MCP servers are local (stdio) — fine for desktop clients, but webclients require a remote server reachable over HTTPS. This is one, packaged tobe deployed and hardened rather than just run.

• Endpoint: https://<your-domain>/mcp
• Auth: none. See Exposure before putting it on the internet.
• Tools:
  • get_current_time(timezone="Europe/Madrid") → date/time for an IANA timezone
  • list_timezones(prefix="") → available IANA timezone names

The reported time is the host's clock, so the host must be NTP-synchronised.That is the service's real correctness dependency; preflight.sh checks it.

Files

1. Run it locally

You need Docker. Nothing else — Python and the dependencies live inside theimage.

git clone https://github.com/ggalancs/current-time-mcp.git
cd current-time-mcp
docker build -t current-time-mcp .
docker run -d --name mcp -p 8000:8000 current-time-mcp

Check it answers:

curl http://127.0.0.1:8000/health
# {"status":"ok","version":"dev","default_timezone":"Europe/Madrid", ...}

Then exercise the actual MCP protocol, which is what a client will do:

pip install mcp                                   # only needed for the test
python smoke_test.py http://127.0.0.1:8000/mcp
# tools: ['get_current_time', 'list_timezones']
# ...
# ALL CHECKS PASSED

Or point the MCP Inspector at it — transport Streamable HTTP, URLhttp://127.0.0.1:8000/mcp:

npx @modelcontextprotocol/inspector

2. Put it on the internet

Web clients such as Claude.ai connect from the vendor's cloud, not from yourmachine, so the server has to be reachable over public HTTPS. A local tunnelor a private network will not do unless you allowlist the vendor's addresses.

You need a domain whose DNS points at your server, and a reverse proxy thatterminates TLS. This repo ships two tested paths.

Path A — behind an existing Nginx Proxy Manager

cp .env.example .env
$EDITOR .env              # NPM_NETWORK (see below), APP_VERSION, DEFAULT_TIMEZONE
docker network ls         # find NPM's network: npm_default, proxy-network, ...
sh preflight.sh           # clock sync, network, config, pinning
docker compose up -d --build
docker compose ps         # expect "healthy"

The container publishes no host port: NPM reaches it by name over the sharedDocker network. Then, once per NPM instance, install the rate-limit zones —follow the header of npm-http-ratelimit.conf. Dothis before the next step: limit_req referencing zones that do not existstops nginx from starting, taking every site it serves with it. Alwaysnginx -t before reloading.

Now create the Proxy Host in NPM:

• Details — Domain: your hostname · Scheme http · Forwardcurrent-time-mcp : 8000 · Block Common Exploits on · WebsocketsSupport off (the transport is SSE over HTTP/1.1, not WebSocket)
• SSL — request a Let's Encrypt certificate, Force SSL, HTTP/2
• Advanced — paste npm-advanced.conf

Path B — self-managed TLS with Caddy

For a host with nothing else on ports 80/443. Set MCP_DOMAIN and ACME_EMAILin .env, then:

docker compose -f docker-compose.caddy.yml up -d --build

Caddy obtains the certificate itself. Dockerfile.caddy builds Caddy with arate-limiting plugin, because the stock image has none.

Then lock the hostname down

Once the proxy works, set ALLOWED_HOSTS to your domain and redeploy:

echo "ALLOWED_HOSTS=mcp.example.com" >> .env
docker compose up -d

Do it in that order. Setting it before the proxy works rejects every requestwith 421, and you will debug the wrong thing.

Verify from outside

curl https://mcp.example.com/health
python smoke_test.py https://mcp.example.com/mcp

3. Register it in Claude.ai

1. Customize → Connectors (it is under Customize, not Settings)
2. "+" → Add custom connector
3. URL: https://mcp.example.com/mcp — including /mcp
4. Leave the OAuth Client ID and Secret empty: this server isunauthenticated
5. Add it, then enable it per conversation with the chat's "+" →Connectors toggle — a connector that exists but is not toggled on looksexactly like a broken server

Ask it something only the tool can answer, such as the current time in Tokyowith seconds. Free accounts are limited to one custom connector; on Team andEnterprise an Owner adds it for the organisation first.

Troubleshooting

Everything here was hit for real while deploying this.

The connector hangs, or tool calls never return. Your proxy is buffering.The transport streams over SSE, and a buffering proxy stalls it. Use theproxy_buffering off block in npm-advanced.conf. Do not addchunked_transfer_encoding off — it is widely copy-pasted into SSE configs andstops nginx framing a body that has no Content-Length.

Every request returns 421. ALLOWED_HOSTS does not match the Host yourproxy forwards. Check for a port suffix; mcp.example.com:* accepts any port.

The container exits immediately on a rebuild. Check the log forModuleNotFoundError: mcp.server.fastmcp. An unpinned mcp installs 2.x, whichremoved that module. See Dependencies.

The container reports healthy but every call fails. An invalidDEFAULT_TIMEZONE now aborts startup instead, so this should be impossible —if you see it, the timezone database is missing (tzdata is inrequirements.txt for exactly this reason).

The connector shows someone else's logo. Clients that fall back to fetching/favicon.ico inherit the favicon of the registrable domain if the subdomainhas none — this server serves its own at /favicon.ico and /icon.png, anddeclares it in the MCP handshake.

The time is wrong. The server reports the host's clock. Runtimedatectl — preflight.sh checks this because nothing else will.

Configuration

Exposure

This server has no authentication. Anyone who can reach the URL can call thetools. The tools only read a clock — no secrets, no side effects — but an openendpoint on the internet still attracts scanners and costs you bandwidth.

Before exposing it publicly, at minimum:

• Set ALLOWED_HOSTS to your public hostname. The MCP spec requiresHost/Origin validation, and the SDK only enables it automatically whenbound to loopback — so a containerised server listening on 0.0.0.0 has itoff unless you set this. Set it after your proxy works, or every requestis rejected with 421.
• Enable the rate limiting shipped here: npm-http-ratelimit.conf plus thelimit_req lines in npm-advanced.conf (nginx), or the rate_limit block inthe Caddyfile (Caddy — needs Dockerfile.caddy, stock Caddy has none).

If you need real access control, put an authenticating proxy in front, orimplement OAuth 2.1 per the MCP specification. Deliberately out of scope here:this repo is the plain server.

Hardening already in place: non-root (uid 10001), read-only root filesystem, allLinux capabilities dropped, no-new-privileges, CPU/memory limits, no publishedhost port, and a stateless transport so an unauthenticated caller cannot growserver memory by repeatedly opening sessions.

Dependencies

requirements.txt is pinned on purpose. mcp 2.x removedmcp.server.fastmcp, so an open version range installs an SDK this servercannot import and the container dies on boot — that actually happened here, andAUDIT.md documents it. Bump deliberately, then re-run smoke_test.py.

Rebuild with --pull periodically anyway: it picks up base-image fixes and afresh tzdata, which a clock server needs when DST rules change.

License

MIT — see LICENSE.

Use it, change it, deploy it, sell it. Attribution is the only condition. It ispublished this way on purpose: the point is that it is worth copying from.