temporal-mcp

temporal-mcp

你的模型懂微积分，却不知道今天是几号。现在就解决这个问题。

temporal-mcp 是一个小巧的模型上下文协议服务，让 LLM Agent 能够感知两轮对话之间的时间。两个工具，几百行代码，标准库 + mcp + platformdirs。就是这么简单。

问题

晚上 11 点开启一个新聊天。模型却说“早上好”。三周后继续一段对话。模型接着上次的话说下去，仿佛时间从未流逝。询问“今天的状态”。得到的却是昨天的状态，或者上周二的状态。

LLM 没有挂钟。它们不知道用户上次发消息是什么时候，不知道日历是否翻了页，也不知道当前是一个新对话，还是一段间隔很久后恢复的对话。大多数时候这无伤大雅。有时却会让你的 Agent 听起来像刚从冷冻睡眠中醒来。

解决方案

为每个对话线程持久保存上次访问时间，并通过两个 MCP 工具公开：

• temporal_tick — 每轮用户对话调用一次。返回模型能够理解的格式，例如 “距离上条消息已经过去 14 分钟，没有跨日，时区为 MDT”。
• temporal_peek — 功能相同，但不会推进状态。适用于你只想了解时间间隔、但不想标记为新一轮对话的情况。

就这样。时间确实存在。你的模型应该知道这一点。

10 秒快速体验

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"])'

你会看到类似这样的内容：

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

运行两次，第二次响应会显示时间间隔。明天再运行，就会看到 day rollover: yes。这就是全部用意。

你会获得什么

每次调用 temporal_tick 都会返回一段易读的标头和一个 JSON 负载：

[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": ""}

标头供模型使用。JSON 供你的代码使用，以便你根据 day_rollover 执行有用的操作（改变问候语、重新加载上下文、重新计算“今天的事项”），或根据 delta_sec 执行操作（降低相关性、检测恢复的会话、标记空闲线程）。

两种使用方式

1. 托管端点 — claude.ai、ChatGPT、移动端

如果你使用 claude.ai 网页版、ChatGPT，或其他需要远程 MCP 服务的客户端，请将连接器指向：

https://temporal-mcp.dev/mcp

根据客户端界面提供的功能，有两种身份验证方式：

A. OAuth 2.0（claude.ai 和 ChatGPT 自定义连接器）

claude.ai 和 ChatGPT 的自定义连接器界面都要求使用 OAuth 2.0，以及客户端 ID 和客户端密钥。托管端点是一个完整的 OAuth 提供方——访问 https://temporal-mcp.dev/connect 并点击生成 OAuth 凭据。你会获得一组全新的 client_id 和 client_secret，仅显示一次。将它们粘贴到客户端的连接器配置中即可。注册就这么简单。

无需电子邮件、密码或账户记录——这组凭据就是身份。我们只存储密钥的 SHA-256，因此不会接触明文。随时可以生成一组新凭据，开启全新的时间线。

Claude.ai 设置： 设置 → 连接器 → 添加自定义连接器。URL 填写 https://temporal-mcp.dev/mcp。粘贴客户端 ID 和客户端密钥。点击连接。自动批准流程会将你重定向回来，claude.ai 会用授权码换取令牌，完成。

ChatGPT 设置： 方法相同——设置 → 连接器 → 自定义 MCP。使用相同的 URL 和凭据。

B. 原始 bearer 令牌（Cursor、Cline、Claude Desktop、Zed、Claude Code）

如果客户端支持自定义 HTTP 标头（大多数都支持），可以跳过 OAuth，只需将任意字符串作为 bearer 令牌发送：

Authorization: Bearer <any opaque string you choose>

可以选用 UUID、密码短语或任何内容。我们会在存储任何内容前先对其进行 SHA-256 哈希；它与 OAuth 流程一样，凭据即身份，但无需繁琐步骤。这是原先最简便的方式，适用于任何允许设置自定义标头的客户端。

C. 嵌入 URL 的令牌（xAI、Grok，以及任何仅支持 URL 的客户端）

如果客户端的连接器界面只提供 URL 字段——不支持请求头、身份验证或 OAuth——请将令牌直接嵌入路径中：

https://temporal-mcp.dev/mcp/<any opaque string you choose>

如果路径形式被剥除，也可以将令牌作为查询参数：

https://temporal-mcp.dev/mcp?token=<any opaque string you choose>

使用相同的 SHA-256 哈希和身份模型。与请求头令牌相比，嵌入 URL 的令牌更容易泄漏（例如通过代理日志、引荐来源），因此这种方式是务实的备用方案，而非默认选项——但我们的威胁模型关注的是“有人推进你的时间线”，而非数据泄露。只要怀疑 URL 被记录在不该记录的地方，就生成一个新的随机字符串来轮换令牌。

无论采用哪种方式

无需注册。无需邮箱。无需个人身份信息。托管端点免费，每个凭据的速率限制为每分钟 60 次请求。如果需求超出此限，可自行托管（见下文）。

2. 本地 stdio——Claude Desktop、Cursor、Cline、Zed、Claude Code

对于桌面/IDE MCP 客户端，使用 pip install 安装 Python 包并在本地运行。无需网络往返，状态保存在本机磁盘上，也无需身份验证。

pip install temporal-mcp

Python 3.9+。支持 Linux、macOS 和 Windows。

以 stdio 模式运行：

temporal-mcp        # or: python -m temporal_mcp

Claude Desktop

{
  "mcpServers": {
    "temporal": {
      "command": "temporal-mcp"
    }
  }
}

Cursor / Cline / 任何其他支持 MCP stdio 的客户端

方法相同——将客户端指向 temporal-mcp 命令。

自行托管远程端点（Cloudflare Workers）

temporal-mcp.dev 上的托管端点运行于 Cloudflare Workers，并由 D1 提供支持。如果你想部署自己的实例——出于隐私、扩展规模的考虑，或将其作为更大型产品的一部分发布——完整的部署内容位于 workers/：

cd workers
npm install
npx wrangler login
npx wrangler d1 create temporal_mcp           # creates the database
# Paste the printed database_id into wrangler.toml
npx wrangler d1 migrations apply temporal_mcp --remote
npx wrangler deploy

免费套餐永久涵盖每天约 100k 次请求。在 [vars] 中设置 REQUIRE_AUTH=true，即可拒绝匿名流量。该 Worker 约有 400 行 TypeScript，并自带单元测试（workers/test/）。

工具

temporal_tick

推进某个线程的时钟并返回快照。每个用户轮次调用一次。

字段	类型	说明
thread_key	string，可选	稳定的对话/会话 ID。claude.ai 网页版：对话 ID。Cursor：窗口/工作区 ID。其他情况：任意对调用方稳定的字符串。省略此项时，将使用默认的主机名 + cwd 哈希——用于本地测试没问题，但不适合服务多个线程。
client_id	string，可选	命名空间标签（例如 "caweb"、"cursor"）。默认为 "mcp"。为不同客户端使用不同标签，避免线程在共享状态中发生冲突。

temporal_peek

只读。结构相同，但不会推进状态。当你需要获取时间间隔增量，但此次调用并非规范的“每个用户轮次推进一次”事件时使用。

状态

每个线程上次看到的状态保存在：

平台	路径
Linux	~/.local/share/temporal-mcp/state.json
macOS	~/Library/Application Support/temporal-mcp/state.json
Windows	%LOCALAPPDATA%\temporal-mcp\state.json

使用 TEMPORAL_MCP_STATE_DIR=/some/path 覆盖默认目录。

状态写入在 POSIX 系统上使用 flock 保证安全，并通过 os.replace 原子替换，因此多个指向同一状态目录的 Agent 不会相互损坏数据。（Windows 会退回到进程内锁——适用于单个 MCP 服务，但不适用于跨进程竞争。）

维护

python -m temporal_mcp gc        # prune threads > 30d idle
python -m temporal_mcp gc 7      # prune threads > 7d idle

刻意不将其作为 MCP 工具公开——能够清理自己关于“我们上次什么时候交谈”的记忆的模型，最终会在最不该清理的时候动手。如果你在意这件事，请通过 cron 运行它。

设计说明（供感兴趣的读者参考）

• 线程键的命名空间格式为 {client_id}:{key}。每个使用场景都应预留唯一的 client_id，以免来自 claude.ai 网页版的线程与共享同一状态目录的本地 Cursor 会话发生冲突。

• 如实报告失败。 如果状态文件无法读取或锁等待超时，快照会返回 available: false，并包含 error 字段，标头则显示 gap: unknown。它不会悄悄谎称这是一个新线程——如果模型认为每一轮对话都是全新的，就会永远说早上好。

• 看门狗。 tick() 在守护线程中运行，超时时间为 100 ms，这样状态读取卡住时就不会耗尽钩子的预算。如果超时，你会得到上述如实报告失败的快照。

• 0.1 版本不支持 HTTP 传输。 仅支持 Stdio——Claude Desktop、Cursor 和其他主流 MCP 客户端实际使用的就是这种方式。如果有需求，HTTP/SSE 可以在 0.2 版本中加入。

路线图

• 0.2 — 可选的 HTTP/SSE 传输、从 Mcp-Session-Id 等标头自动解析会话 ID、可配置的时区覆盖
• 0.3 — 可选择启用“长间隔”阈值（超过 N 小时后返回 resume: true 标志），让 Agent 无需自行计算即可判断是否要针对恢复的会话采取不同分支

许可证

MIT。请参阅 LICENSE。

作者

由 Garret Sutherland / MirrorEthic LLC 构建，提取自一个更大型认知网格项目的时间层。在该项目中，这个基础组件的重要性足以让它拥有独立的软件包。

---

_{mcp-name: io.github.MirrorEthic/temporal-mcp}