temporal-mcp server

temporal-mcp

Your model knows calculus but not what day it is. Fix that.

temporal-mcp is a tiny Model Context Protocol server that gives LLM agents a sense of time between turns. Two tools, a few hundred lines, stdlib + mcp + platformdirs. That's the whole thing.

The problem

Open a fresh chat at 11 PM. The model says "good morning." Resume a conversation three weeks later. The model picks up mid-sentence like no time passed. Ask for "today's status." Get yesterday's status. Or last Tuesday's.

LLMs don't have wall clocks. They don't know when the last user message was, whether the calendar flipped, or whether this is a fresh thread or one resumed after a long gap. Most of the time this is harmless. Sometimes it makes your agent sound like it just woke up from cryosleep.

The fix

A persistent per-thread last-seen log, exposed as two MCP tools:

14 minutes since the last message, no day rollover, timezone MDT"* in a format the model can actually read.

• temporaltick — call this once per user turn. Returns "it has been

want the gap without claiming a turn.

• temporalpeek** — same thing, but doesn't advance state. For when you

That's it. Time exists. Your model should know that.

Try it in 10 seconds

curl -s -X POST https://temporal-mcp.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(uuidgen)" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "name":"temporal_tick",
        "arguments":{"thread_key":"try-it","tz_offset_minutes":-360,"tz_name":"MDT"}}}' \
| python3 -c 'import sys,json; print(json.load(sys.stdin)["result"]["content"][0]["text"])'

You'll see something like:

[temporal] Wed May 13, 10:42 AM MDT | fresh thread (no prior history)
{...JSON payload...}

Run it twice and the second response shows the gap. Run it tomorrow and you'll get day rollover: yes. That's the whole point.

What you get

Every tick returns a human-readable header and a JSON payload:

[temporal] Wed May 13, 9:42 AM MDT | last prompt 14m ago (Wed 9:28 AM)

{"thread_key": "mcp:abc123", "now": 1747158120.0, "prev": 1747157280.0,
 "delta_sec": 840, "day_rollover": false, "fresh_thread": false,
 "tz_name": "MDT", "tz_offset_sec": -21600, "available": true, "error": ""}

The header is for the model. The JSON is for your code, in case you want to do something interesting with dayrollover (greet differently, reload context, recompute "today's items") or with deltasec (decay relevance, detect a resumed session, flag idle threads).

Two ways to use it

1. Hosted endpoint — claude.ai, ChatGPT, mobile

If you use claude.ai web, ChatGPT, or anything else that wants a remote MCP server, point your connector at:

https://temporal-mcp.dev/mcp

There are two ways to authenticate, depending on what your client UI exposes:

A. OAuth 2.0 (claude.ai and ChatGPT custom connectors)

Both claude.ai and ChatGPT's custom connector UIs require OAuth 2.0 with a Client ID and Client Secret. The hosted endpoint is a full OAuth provider — visit https://temporal-mcp.dev/connect and click Generate OAuth Credentials. You'll get a fresh clientid + clientsecret pair, shown once. Paste them into your client's connector config. That's the entire signup.

No email, no password, no account record — the credential pair is the identity. We store only a SHA-256 of the secret, so we never see the plaintext. Generate a new pair any time you want a fresh timeline.

Claude.ai setup: Settings → Connectors → Add custom connector. URL https://temporal-mcp.dev/mcp. Paste your Client ID and Client Secret. Connect. The auto-approve flow redirects you back, claude.ai exchanges the code for a token, and you're done.

ChatGPT setup: Same idea — Settings → Connectors → Custom MCP. Same URL, same credentials.

B. Raw bearer token (Cursor, Cline, Claude Desktop, Zed, Claude Code)

Shortened. The full README is on GitHub.