temporal-mcp-server

用于时间、时区和持续时间工具的 MCP 服务器。

可以通过 stdio 在本地运行（Claude Desktop、Claude Code、任何本地 MCP 客户端），通过 HTTP 本地运行，或使用 托管实例 —— 相同的工具、相同的代码，三种运行方式。

公共实例运行在 Cloudflare Workers 上，地址为 https://time.somamcp.com/mcp：

claude mcp add --transport http temporal https://time.somamcp.com/mcp

基于 somamcp 构建，后者为两种运行时提供 MCP 管道、遥测以及健康/自省端点。时间逻辑是纯粹且函数式的，使用 functype。

工具

somamcp 还注册了一个 info 工具以及 /health、/health/detail、/info 和 /dashboard 端点。

值得一提的行为

月份运算采用钳制而非溢出。 对 2026-01-31 使用 P1M 调用 add_duration 返回 2026-02-28，而不是 2026-03-03。将“一个月”加到长月的末尾会落在短月的末尾。

偏移量按瞬间解析，而非按区解析。 America/New_York 在八月报告 -04:00，在一月报告 -05:00。夏令时来自运行时的 tz 数据库，因此这里没有会过时的偏移量表。

错误带有提示。 未知时区会返回错误值以及预期格式，因此调用代理可以自行纠正，而不是再次猜测。

Related MCP server: mcp-datetimeday

作为本地 MCP 服务器运行

Stdio 是默认模式，也是本地客户端所期望的模式。不托管任何内容，不监听端口——你的客户端启动该进程并通过 stdin/stdout 与之通信。

Claude Code

claude mcp add temporal -- npx -y temporal-mcp-server

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "temporal": {
      "command": "npx",
      "args": ["-y", "temporal-mcp-server"]
    }
  }
}

在 macOS 上，该文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上，位于 %APPDATA%\Claude\claude_desktop_config.json。编辑后请重启 Claude Desktop。

从克隆运行

如果你不想通过 npm：

pnpm install
pnpm build
pnpm start          # stdio

然后将你的客户端指向构建后的入口点：

claude mcp add temporal -- node /absolute/path/to/temporal-mcp-server/dist/node.js

{
  "mcpServers": {
    "temporal": {
      "command": "node",
      "args": ["/absolute/path/to/temporal-mcp-server/dist/node.js"]
    }
  }
}

该包还会安装一个 temporal-mcp-server 二进制文件，因此全局安装（npm i -g temporal-mcp-server）后，你可以直接将该名称用作命令。

验证是否正常

服务器在 stdout 上使用 JSON-RPC 通信，因此你可以手动驱动它：

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_current_time","arguments":{"timezone":"Asia/Tokyo"}}}' \
  | node dist/node.js

只有 JSON-RPC 会输出到 stdout；日志输出到 stderr，因此管道是安全的。

在本地通过 HTTP 运行

对于支持流式 HTTP 而非 stdio 的客户端：

pnpm start:http     # http://localhost:3333/mcp — override the port with PORT

这是相同的服务器和相同的工具；只是传输方式不同。

在 Cloudflare Workers 上远程运行

pnpm cf:dev         # local workerd runtime
pnpm cf:deploy      # build + edge-safety check + deploy

cf:deploy 首先运行 pnpm build，其中包含 check:worker —— 因此带有 Node 内置模块的包会在任何内容到达 Cloudflare 之前失败。

持续部署

部署通过 Cloudflare Workers Builds 而非 GitHub Actions 进行，因此 GitHub 中完全不存储 Cloudflare API 令牌——Cloudflare 通过自己的 GitHub App 连接到仓库。

在仪表板中设置一次（Workers & Pages → temporal-mcp-server → Settings → Build）：

将部署命令指向包脚本可将门控逻辑保留在版本控制中；仪表板只保留一行稳定配置。仪表板中的 Worker 名称必须与 wrangler.jsonc 中的 name（temporal-mcp-server）匹配，否则构建会失败。

构建镜像自带 pnpm 并遵循 .nvmrc（我们的镜像固定 Node 24）。非生产分支默认使用 npx wrangler versions upload，因此分支推送会生成预览版本，而不会影响线上部署。

MCP 端点位于 /mcp。若要要求 Bearer 令牌：

wrangler secret put MCP_AUTH_TOKEN

设置 MCP_AUTH_TOKEN 后，未经身份验证对 /mcp 的调用会收到 401。如果未设置，端点将公开——对时钟来说合理，但对其他服务则不然。

可选 vars：GIT_COMMIT 和 ENVIRONMENT 由 info 工具和 /info 显示。

将客户端连接到已部署的 worker

公共实例通过自定义域名提供服务：

claude mcp add --transport http temporal https://time.somamcp.com/mcp

如果设置了令牌，请将其作为请求头传递：

claude mcp add --transport http temporal https://time.somamcp.com/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

健康检查：https://time.somamcp.com/health。

pnpm cf:dev 在 http://localhost:8787/mcp 上提供相同内容，因此你可以在部署之前将客户端指向本地 workerd 实例。

为什么 worker 要导入 somamcp/edge

somamcp 的根桶文件重新导出了导入 node:fs 的辅助函数。从 Worker 导入它会将 Node 内置模块拖入包中。因此 src/worker.ts 导入 somamcp/edge，并且如果 node: 导入、裸 Node 内置模块或根 somamcp 说明符到达 worker 包，pnpm check:worker 会使构建失败。

该检查从 dist/worker.js 遍历实际的导入图，而不是匹配文件名——打包器会将与 Node 入口共享的代码提升到带有生成名称的块中，而文件名通配符会跳过最可能携带泄漏的那个文件。

nodejs_compat 被有意地未在 wrangler.jsonc 中启用。如果将来出现 Node 内置模块，构建应该大声失败，而不是被静默填充。

wrangler.jsonc 中的 alias 块

xsschema（通过 fastmcp 传递）会通过动态导入探测它支持的每个 schema 库——valibot、effect、sury。我们只使用 zod，因此这些分支永远不会运行，但 esbuild 仍然必须解析这些说明符。它们被别名指向一个空模块，而不是安装三个未使用的库。

架构

src/
  clock.ts    pure time logic — Either<TemporalError, T>, no I/O, no globals
  tools.ts    MCP tool registration; takes a server, creates none
  index.ts    library surface (runtime-agnostic)
  node.ts     entry: somamcp      -> stdio + httpStream
  worker.ts   entry: somamcp/edge -> export default { fetch }

registerTemporalTools(server) 接收服务器而不是构建一个，因此两个入口点注册的工具完全相同。clock.ts、tools.ts 或 index.ts 中的任何内容都不会触及 process、文件系统或任何 Node 内置模块。

失败是值。clock.ts 中每个可能失败的函数都返回 Either<TemporalError, T>；工具层将 Left 折叠为 MCP 错误结果。没有任何依赖堆栈展开，这使得相同的逻辑可以在两种运行时上原封不动地运行。

开发

pnpm validate       # format + lint + typecheck + test + build
pnpm test           # 34 tests
pnpm check:worker   # verify the worker bundle is edge-safe

test/worker.spec.ts 通过 MCP 线上协议驱动真实的 Request 对象穿过 Worker 的 fetch 处理程序，因此集成问题会在 CI 中暴露，而不是在部署后。

许可证

MIT