clockify-mcp 是一个面向 Clockify 时间追踪 API 的 Model Context Protocol（MCP）服务器，目标是让 AI 助手通过自然语言访问 Clockify 数据，例如查询工作区、项目和时间条目，生成报告、记录工时，以及管理客户、发票等。项目宣称覆盖 18 个领域、共 112 个工具，并采用三层访问模型：只读、时间追踪、完全访问。
主要能力
- 工具覆盖：112 个工具分布在 18 个领域，包括发票、排班、休假与审批等。
- 只读工具：当前提供 48 个只读工具（Phase 0–8b，18 个领域）。
- 写入工具：64 个写入工具（创建/更新/删除客户、项目、任务、标签、时间条目、假日、费用与费用类别，以及休假政策/请求管理、审批提交/重新提交/更新、自定义字段创建/更新/删除与项目分配、排班分配管理、发票与付款管理、共享报告管理、Webhook 创建/更新/删除/令牌）。这些工具在设置 CLOCKIFY_ACCESS_MODE=full（或向后兼容的 CLOCKIFY_ENABLE_WRITES=true）时注册。
- 中间模式：time-tracking 模式仅暴露用于记录工时的时间条目写入工具。
- 付费功能提示：休假、假日、费用、审批、自定义字段、排班、发票和 Webhook 属于 Clockify 付费功能，在没有相应套餐时这些工具会返回错误（HTTP 402/403/404）。generate_attendance_report 和 generate_expense_report（以及针对这两类的 export_report）需要工作区的考勤/费用附加组件；基于时间的报告（detailed/summary/weekly）和共享报告在免费套餐上可用。
- 可观测性：可选启用 OpenTelemetry 追踪、指标和日志，供应商中立，可导出到任何兼容 OTLP 的后端（如 Dynatrace、Grafana、Datadog、Jaeger 等）。禁用时不会导入 opentelemetry。
使用方式
- 一键安装：下载预构建的 clockify-mcp.mcpb 并双击，Claude Desktop 会打开安装程序并提示输入 Clockify API 密钥，无需 Python、npx/uvx 或配置文件。该 .mcpb 附在每个 GitHub Release 上，并在 Smithery 上镜像。
- 也可使用包管理器或容器运行，或在不安装的情况下运行（需要 uv）。容器镜像每次发布都会推送到 GHCR。
- 连接 Claude Desktop：在 claude_desktop_config.json 中添加配置并重启 Claude Desktop，然后可询问“What workspaces do I have in Clockify?”。
- 获取 API 密钥：登录 Clockify → Profile Settings → API → 复制 API 密钥。
- 配置解析顺序（优先级从高到低）：环境变量（始终优先）、位于 ~/.config/clockify-mcp/config.toml 的 TOML 配置。
- 访问模式：read 仅暴露只读工具；time-tracking 增加时间条目写入工具（create/update/delete/duplicate/bulk）用于记录工时，不包含其他写入；full 暴露所有写入工具。该设置决定服务器注册哪些 MCP 工具，不能替代 API 密钥自身的权限。
- 运行方式：默认 STDIO 保持本地；sse 和 streamable-http 传输没有内置认证，仅应在绑定回环地址或置于带认证的反向代理之后使用。
- 工作区范围：几乎所有 Clockify 操作都限定在工作区（/workspaces/{workspaceId}/...）。工具接受可选的 workspace_id；省略时回退到 CLOCKIFY_DEFAULT_WORKSPACE_ID。若两者都未设置，工具会要求先通过 list_workspaces 解析一个工作区。
- 分页：列表工具接受可选的 page/page_size 并返回一页。高容量列表（list_time_entries、list_projects、list_clients、list_tasks、list_tags、list_users）还接受 fetch_all=true 以跟随分页并返回所有页拼接结果（可能发起多次 API 调用）。
- 错误分类：失败会带有类别——PLAN_REQUIRED、ACCESS_DENIED 或 AUTH，以便助手判断是提示升级套餐、启用模块还是修复密钥。
适用场景
- 通过自然语言查询 Clockify 工作区、项目和时间条目。
- 生成报告（基于时间的 detailed/summary/weekly 报告、共享报告，以及需要附加组件的考勤/费用报告）。
- 记录工时（time-tracking 模式）。
- 管理客户、发票、付款、排班、休假、审批、自定义字段和 Webhook（需相应套餐与模块，且需开启写入）。
限制与注意事项
- 默认只读；写入需显式开启。写入模式允许连接的代理通过你的 Clockify 凭据创建、修改和删除真实数据；delete_* 工具和 withdraw_time_off_request 不可逆。
- 许多领域受两个独立条件限制：工作区套餐必须包含该功能（否则 API 返回 402 或订阅消息，服务器抛出 PLAN_REQUIRED）；且模块必须在工作区中启用（即使套餐正确，管理员也需在 Clockify → Workspace Settings 中开启 Time off、Expenses、Approval、Invoicing、Scheduling；否则 API 返回 403 Access Denied，服务器抛出 ACCESS_DENIED）。自定义字段、Webhook 和报告无需单独开关。
- 在 time-tracking 模式中，duplicate/bulk 始终作用于已认证用户；对于按 id 的 update/delete，助手会被提示在触碰可能属于他人的条目之前先确认。
- OTLP 端点和标头通过标准 OpenTelemetry 环境变量配置（不在 TOML 文件中）。CLOCKIFY_TELEMETRY_DETAIL 控制附加多少参数/负载数据（metadata 默认 → ids → full）；API 密钥始终被脱敏。所需令牌范围：openTelemetryTrace.ingest、metrics.ingest、logs.ingest。Dynatrace 的 OTLP 指标摄取需要 delta 时间性，否则指标导出会以 400 Bad Request 失败。
- 关于具体安装命令、配置示例、价格与套餐细节，资料中未完整提供，暂未提供。