clockify-mcp-server

通过让代理（agent）代替你在网页界面中点击操作，在 Clockify 中记录你的项目工时。

“每天早上给 ACME 加 4 小时，每天下午给 Evil Corp 加 4 小时”

→ 一次批准提示，创建 10 条记录，共 40 小时。

一个本地 stdio MCP 服务器。每个人使用自己的 API 密钥自行运行——不共享，也不托管任何内容。

时间始终相对于你的 Clockify 个人资料时区。 你说 09:00，服务器会从你的 Clockify 个人资料中读取 settings.timeZone 并转换为 UTC。你永远不需要处理 UTC，代理也不需要。

尚不支持：标签、客户、正在运行的计时器（开始/停止）、编辑现有条目、报告。

使用方法

如果你只想记录时间，这里有你所需的一切。大约需要两分钟。

1. 安装 bun（在 1.3.14 上测试）和依赖项：

curl -fsSL https://bun.sh/install | bash # install bun if needed
git clone <this-repo> && cd clockify-mcp-server
bun install

没有构建步骤——bun 直接运行 TypeScript。

2. 获取你的 Clockify API 密钥：

• Clockify → 你的头像 → Preferences → ADVANCED 标签页 → Manage API keys → GENERATE NEW

3. 将服务器注册到你的代理中。

Claude Code — 从你刚刚克隆到的仓库根目录，原样复制以下内容：

claude mcp add clockify -s user -e CLOCKIFY_API_KEY=<key> -- bun "$PWD/src/index.ts"

-s user 会将其写入你的个人配置，因此它会在每个项目中加载，而不仅仅是这个项目（默认作用域 local 会将其绑定到当前目录）。$PWD 会在 claude 看到它之前由你的 shell 展开，因此存储的路径是绝对路径。

任何其他工具（Cursor、VS Code、Zed、Claude Desktop…）——在其 MCP 配置中做同样的三件事。打印要粘贴的路径：

echo "$PWD/src/index.ts"

{
  "mcpServers": {
    "clockify": {
      "command": "bun",
      "args": ["<paste the absolute path here>"],
      "env": { "CLOCKIFY_API_KEY": "<key>" }
    }
  }
}

路径必须是绝对路径：你的代理会从它所在的任何目录启动服务器，而不是从这个仓库。

4. 检查 — 在新的会话中：

list my clockify projects
log 2 hours on <project> today from 09:00 to 11:00, description test
show my clockify entries for this week
delete that entry

在第二个提示后打开 Clockify Web 界面，确认条目显示为 09:00–11:00。如果显示的是其他时间，说明你的 Clockify 个人资料时区与预期不符——请在 Clockify 偏好设置中修复，这里的一切都取决于它。

环境变量

如果出现问题

• CLOCKIFY_API_KEY is not set — 密钥未到达服务器进程。请将其放在工具配置的 env 中，而不是你的 shell 中。

• Ambiguous project "x". Candidates: … — 这是有意为之。服务器拒绝猜测 id；请使用列出的名称之一。

• 每次调用都返回 404 — 你的工作区位于区域主机上。请设置 CLOCKIFY_API_BASE。

• 条目时间不对 — 请检查你的 Clockify 个人资料时区（参见步骤 4）。

开发

仅使用服务器不需要这些。

bun test      # unit tests, no network
bun run check # biome format + lint, applies fixes
bun run start # start the server on stdio (needs CLOCKIFY_API_KEY)

bun install 也会安装 git 钩子（prepare → lefthook install），因此 biome check --write 会在提交时对暂存文件运行，并重新暂存其修复的内容。无需其他设置。

对于本地运行，bun 会从仓库根目录自动加载 .env，因此在那里放置一个被 git 忽略的 CLOCKIFY_API_KEY=<key> 可以省去重新输入的麻烦。这仅在当前工作目录就是仓库时才有效，这就是为什么上面的工具配置会显式传递密钥。

目录结构

src/clockify.ts      # API client, memoised user/project/task lookups, timezone conversion
src/index.ts         # McpServer + the four tools + stdio wiring
src/clockify.test.ts # the parts worth testing: DST conversion, name resolution, payload building
docs/                # Clockify API request/response samples
plans/               # what was built and what was deliberately left out

有趣的代码是 src/clockify.ts 中的 localToUtc / interval —— 一个标准库 Intl.DateTimeFormat 往返，没有使用日期库。修改后运行 bun test；夏令时相关的测试用例是捕捉错误的关键。

将程序分发给没有 bun 的用户：bun build --compile --outfile clockify-mcp src/index.ts 会生成一个自包含的二进制文件，供工具直接使用。