temporal-mcp-server

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（README · npm）构建，它为两种运行环境提供 MCP 基础设施、遥测以及健康状态和自省端点。时间逻辑纯粹且函数式，使用 functype。

工具

工具	用途
get_current_time	获取当前时间，包含纪元时间、UTC ISO-8601 时间和任意 IANA 时区的挂钟时间
convert_timezone	将 ISO-8601 时间戳转换为目标时区的表示形式
add_duration	对 ISO-8601 时长进行加减运算，月份计算会考虑日历规则
time_between	计算两个时间戳之间经过的时间，以整单位和易读摘要表示

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

值得了解的行为

日期单位按日历计算；时间单位则精确计算。 这种区别能正确处理夏令时，并遵循 ISO-8601 和 Temporal：

美国“秋季拨回”期间	结果
2026-11-01T00:00-04:00 + P1D	2026-11-02T00:00 — 次日同一挂钟时间（实际经过 25 小时）
2026-11-01T00:00-04:00 + PT24H	2026-11-01T23:00 — 正好 24 小时

两种结果都正确，但并不相同。“明天”是日历概念；“从现在起 24 小时”则是物理时间概念。

timezone 决定运算方式，而不只是显示方式。 日历单位会根据该时区的挂钟时间进行计算，因此在 America/New_York 中使用 add_duration，结果会符合纽约当地人的预期。

月份计算会截断，而不是溢出。 对 2026-01-31 加上 P1M，结果是 2026-02-28，而不是 2026-03-03。

偏移量按具体时刻解析，而不是按时区固定解析。 America/New_York 在 8 月会报告 -04:00，在 1 月会报告 -05:00。夏令时信息来自运行时的时区数据库，因此这里不存在会过时的偏移量表。

不带时区信息的时间戳会按提供的时区解析。 2026-11-01T00:00:00 配合 America/New_York 表示纽约时间的午夜。它绝不会回退到主机时区——否则，笔记本电脑和 Worker 给出的结果可能不同。

时间戳解析严格。 只接受 ISO-8601 格式；17 Aug 2026 会被拒绝并附上提示。new Date() 则会接受该值，并根据进程恰好运行所在的时区进行解析。

经过时间的各组成部分统一使用同一符号。 对于反向时间区间，time_between 返回的 days/hours/minutes/seconds 都是负数，因此相加结果正确；此外还会返回 past/future/same 形式的 direction。

错误信息会附带提示。 遇到未知时区时，会同时返回错误值和预期格式，让调用方 Agent 可以自行修正，而不必再次猜测。

作为本地 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）后，可以直接将该名称用作命令。

在此仓库中开发

已提交到仓库的 .mcp.json 会将本地构建注册为 temporal 服务，因此 Claude Code 会使用你的更改，而不是托管实例：

{
  "mcpServers": {
    "temporal": {
      "command": "node",
      "args": ["dist/node.js"]
    }
  }
}

先运行 pnpm build——它指向 dist/，因此未构建的检出版本没有可启动的内容。

验证是否正常运行

该服务通过 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）：

字段	值
部署命令	pnpm cf:deploy
构建命令	(留空——cf:deploy 会执行构建)
根目录	(仓库根目录)

将部署命令指向软件包脚本，可将门控逻辑保留在版本控制中；控制面板中只需保留一行固定配置。控制面板中的 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。若不设置，该端点将公开访问——对于时钟来说尚可，对大多数其他用途则不然。

构建溯源信息

scripts/deploy.mjs 会使用 GIT_COMMIT、GIT_BRANCH 和 BUILD_DATE 标记部署信息，因此 info 工具和 /info 会准确报告正在运行的内容：

curl -s https://time.somamcp.com/info   # protected; also available via the `info` MCP tool

Workers Builds 会在构建期间提供 WORKERS_CI_COMMIT_SHA 和 WORKERS_CI_BRANCH，但构建变量在运行时不可读取——必须将它们转发为 Worker 变量，部署脚本正是这样做的。在本地运行 pnpm cf:deploy 时会回退到 git rev-parse；从有未提交更改的工作树部署时，标记会写成 <sha>-dirty，而不会冒称为实际并非如此的提交。

将客户端连接到已部署的 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 的根 barrel 会重新导出一些导入 node:fs 的辅助函数。在 Worker 中导入它会把 Node 内置模块带进构建包。因此，src/worker.ts 导入 somamcp/edge，而如果 node: 导入、裸 Node 内置模块或根 somamcp 标识符进入 Worker 构建包，pnpm check:worker 就会导致构建失败。

有关完整说明，请参阅 somamcp 的边缘运行时文档，其中还包括一张功能兼容性表，介绍边缘环境中哪些功能可用、哪些不可用——stdio、会话、reportProgress 和多结果资源都仅适用于 Node。

这项检查会从 dist/worker.js 遍历实际的导入图，而不是匹配文件名——打包器会把与 Node 入口共用的代码提升到一个名称自动生成的分块中，而文件名 glob 恰恰会跳过最可能包含泄漏的文件。

wrangler.jsonc 中有意未启用 nodejs_compat。如果有 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