current-time — remote MCP server

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

Most time MCP servers are local (stdio) — fine for desktop clients, but web clients require a remote server reachable over HTTPS. This is one, packaged to be 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="UTC") → 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

File	Purpose
server.py	The server (Streamable HTTP on /mcp, plus /health and an icon)
requirements.txt	Python deps — pinned, see Dependencies
Dockerfile	Hardened image (non-root, read-only-friendly, healthcheck)
healthcheck.py	HTTP /health probe used by Docker
docker-compose.yml	App joined to an existing Nginx Proxy Manager network
npm-advanced.conf	SSE-friendly + rate-limited snippet for the NPM Proxy Host
npm-http-ratelimit.conf	Rate-limit zones for NPM's nginx http context
docker-compose.caddy.yml · Caddyfile · Dockerfile.caddy	Alternative: self-managed TLS with Caddy (rate-limit plugin compiled in)
preflight.sh	Pre-deploy checks: clock sync, network, config, pinning
smoke_test.py	End-to-end client test over Streamable HTTP
AUDIT.md	What was found and fixed while hardening this, with evidence

1. Run it locally

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

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":"UTC", ...}

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, URL http://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 your machine, so the server has to be reachable over public HTTPS. A local tunnel or 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 that terminates 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 shared Docker network. Then, once per NPM instance, install the rate-limit zones — follow the header of npm-http-ratelimit.conf. Do this before the next step: limit_req referencing zones that do not exist stops nginx from starting, taking every site it serves with it. Always nginx -t before reloading.

Now create the Proxy Host in NPM:

• Details — Domain: your hostname · Scheme http · Forward current-time-mcp : 8000 · Block Common Exploits on · Websockets Support 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_EMAIL in .env, then:

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

Caddy obtains the certificate itself. Dockerfile.caddy builds Caddy with a rate-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 request with 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 is unauthenticated
5. Add it, then enable it per conversation with the chat's "+" → Connectors toggle — a connector that exists but is not toggled on looks exactly like a broken server

Ask it something only the tool can answer, such as the current time in Tokyo with seconds. Free accounts are limited to one custom connector; on Team and Enterprise 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 the proxy_buffering off block in npm-advanced.conf. Do not add chunked_transfer_encoding off — it is widely copy-pasted into SSE configs and stops nginx framing a body that has no Content-Length.

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

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

The container reports healthy but every call fails. An invalid DEFAULT_TIMEZONE now aborts startup instead, so this should be impossible — if you see it, the timezone database is missing (tzdata is in requirements.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 subdomain has none — this server serves its own at /favicon.ico and /icon.png, and declares it in the MCP handshake.

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

Configuration

Variable	Default	Purpose
DEFAULT_TIMEZONE	UTC	Timezone when the caller passes none. Validated at startup — an invalid value aborts the boot. UTC on purpose: a geographic default hands the wrong region's time to everyone else, with nothing to signal it.
ALLOWED_HOSTS	(unset)	Comma-separated Host allowlist. Set this in production (see below).
ALLOWED_ORIGINS	(unset)	Optional Origin allowlist. An absent Origin is always allowed.
FORWARDED_ALLOW_IPS	127.0.0.1	Which upstreams may set X-Forwarded-For. Set to * only when the app port is unpublished and reachable solely by your proxy.
PUBLIC_URL	(unset)	Advertised as the server's website_url in the MCP handshake.
APP_VERSION	dev	Build stamp, reported on /health.

Exposure

This server has no authentication. Anyone who can reach the URL can call the tools. The tools only read a clock — no secrets, no side effects — but an open endpoint 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 requires Host/Origin validation, and the SDK only enables it automatically when bound to loopback — so a containerised server listening on 0.0.0.0 has it off unless you set this. Set it after your proxy works, or every request is rejected with 421.
• Enable the rate limiting shipped here: npm-http-ratelimit.conf plus the limit_req lines in npm-advanced.conf (nginx), or the rate_limit block in the Caddyfile (Caddy — needs Dockerfile.caddy, stock Caddy has none).

If you need real access control, put an authenticating proxy in front, or implement 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, all Linux capabilities dropped, no-new-privileges, CPU/memory limits, no published host port, and a stateless transport so an unauthenticated caller cannot grow server memory by repeatedly opening sessions.

Dependencies

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

Rebuild with --pull periodically anyway: it picks up base-image fixes and a fresh 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 is published this way on purpose: the point is that it is worth copying from.