Clockify Time Tracking

clockify-mcp

一个用于 Clockify 时间跟踪 API 的 Model Context Protocol 服务。

让 AI 助手访问你的 Clockify 数据——查询工作区、项目和时间记录，生成报告、记录工时，以及管理客户、发票等，所有操作均可通过自然语言完成。

涵盖 18 个领域的 112 个工具。默认只读，可通过明确选择启用写入操作。

一键安装

将此服务与 Claude Desktop（以及其他兼容 MCPB 的客户端）搭配使用，最简单的方式是下载预构建程序包：

➡️ 下载 clockify-mcp.mcpb——然后双击。Claude Desktop 会打开安装程序，提示你输入 Clockify API 密钥，之后即可使用。无需 Python、无需 npx/uvx，也无需配置文件。

每个 GitHub Release 都附带 .mcpb，并在 Smithery 上提供镜像。想使用包管理器或容器？请参阅下方的快速开始。

它能做什么？

目前提供 48 个只读工具（第 0–8b 阶段——18 个领域）。设置 CLOCKIFY_ACCESS_MODE=full（或旧版兼容设置 CLOCKIFY_ENABLE_WRITES=true）后，会注册 64 个写入工具（用于创建、更新和删除客户、项目、任务、标签、时间记录、假期、费用和费用类别，以及管理休假政策/申请、提交/重新提交/更新审批、创建/更新/删除自定义字段并分配给项目、管理排班分配、管理发票和付款、管理共享报告，以及创建/更新/删除 Webhook/令牌）。中间档 time-tracking 模式仅开放用于记录工时的时间记录写入工具——请参阅访问模式。

† 休假、节假日、费用、审批、自定义字段、排期、发票和 Webhook 是 Clockify 的付费功能；对于不包含这些功能的套餐，这些工具会报错（HTTP 402/403/404）。 ‡ generate_attendance_report 和 generate_expense_report（以及针对这两种类型的 export_report）需要工作区的考勤/Expenses 附加功能；基于工时的报告（详细/摘要/每周）和共享报告可在免费套餐中使用。

写入工具（选择启用 — 设置 CLOCKIFY_ACCESS_MODE=full）：

create_expense 和 update_expense 可接收可选的本地收据文件，并通过 multipart 上传。

快速开始

1. 安装

pip install clockify-mcp

或者不安装直接运行（需要 uv）：

uvx clockify-mcp

或者使用容器镜像（每次发布时都会推送到 GHCR）：

docker run --rm -i -e CLOCKIFY_API_KEY=your-key ghcr.io/tracegazer/clockify-mcp:latest

2. 连接到 Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "clockify": {
      "command": "uvx",
      "args": ["clockify-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key"
      }
    }
  }
}

重启 Claude Desktop。提问：“我在 Clockify 中有哪些工作区？”

{
  "mcpServers": {
    "clockify": {
      "command": "clockify-mcp",
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "clockify": {
      "command": "uvx",
      "args": ["clockify-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key",
        "CLOCKIFY_ACCESS_MODE": "full"
      }
    }
  }
}

3. 获取 API 密钥

登录 Clockify → 个人资料设置 → API → 复制你的 API 密钥。

配置

配置按以下顺序解析（优先级从高到低）：

1. 环境变量（始终优先）
2. ~/.config/clockify-mcp/config.toml 中的 TOML 配置

访问模式：read 仅开放读取工具。time-tracking 会额外开放时间条目写入工具（create/update/delete/duplicate/bulk），用于记录工时，除此之外不开放其他工具——duplicate/bulk 始终针对已通过身份验证的用户操作；对于按 ID 执行的 update/delete，助手会被要求在修改可能属于其他人的条目之前进行确认。full 会开放所有写入工具。此设置用于控制服务注册哪些 MCP 工具；它不能替代 API 密钥自身的权限。

请参阅 config.toml.example 获取可直接复制粘贴的模板。

# ~/.config/clockify-mcp/config.toml
api_key = "your-clockify-api-key"
# region = "global"
# default_workspace_id = ""
# access_mode = "read"   # read | time-tracking | full

**提示：**请先创建配置目录：mkdir -p ~/.config/clockify-mcp

运行服务

clockify-mcp                       # STDIO transport (default)
clockify-mcp --transport sse       # SSE/HTTP transport

**安全说明：**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 中启用方法。

付费功能及在 Clockify 中启用方法

许多功能领域受两个相互独立的条件限制——两者都满足，工具才能正常工作：

1. 工作区套餐必须包含该功能。 否则，API 会返回 402（或“subscription”消息），服务会抛出类别为 PLAN_REQUIRED 的 ClockifyAPIError。

2. 必须在工作区中启用该模块。 即使套餐符合要求，管理员也必须在 Clockify → Workspace Settings 中启用以下模块：Time off、Expenses、Approval、Invoicing、Scheduling。启用前，API 会返回 403 "Access Denied"，服务会抛出类别为 ACCESS_DENIED 的 ClockifyAPIError。（自定义字段、webhooks 和报告无需单独启用。）

操作失败时，错误类别会说明应采取的措施：

• PLAN_REQUIRED — 升级工作区套餐（Standard／Pro）。
• ACCESS_DENIED — 在 Workspace Settings 中启用该功能，或检查 API 密钥用户的角色／权限。
• AUTH — API 密钥缺失、无效或已撤销。

可观测性（可选）

服务可以发送 OpenTelemetry 跟踪、指标和日志——完全由你选择启用，且与供应商无关。可导出到任何兼容 OTLP 的后端（Dynatrace、Grafana、Datadog、Jaeger 等）。禁用时，不会导入 opentelemetry。

pip install "clockify-mcp[telemetry]"

export CLOCKIFY_TELEMETRY=1

OTLP 端点和标头通过标准 OpenTelemetry 环境变量配置（不在 TOML 文件中）。CLOCKIFY_TELEMETRY_DETAIL 控制附加的参数／负载数据量（默认为 metadata → ids → full）；API 密钥始终会被隐藏。

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-env>.live.dynatrace.com/api/v2/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token <YOUR_DT_TOKEN>"
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
export OTEL_SERVICE_NAME=clockify-mcp

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_SERVICE_NAME=clockify-mcp

发送的信号：

• 跟踪 — 每次 MCP 工具调用（execute_tool <name>）和每次 Clockify API 请求都会生成一个 span
• 指标 — mcp.tool.duration、mcp.tool.errors，以及 Clockify 客户端请求耗时
• 日志 — 工具错误和异常的 API 响应结构，并与跟踪关联（仅限 OTLP，绝不输出到 stdout）

开发

git clone https://github.com/tracegazer/clockify-mcp
cd clockify-mcp
uv sync --extra dev

CLOCKIFY_API_KEY=dummy uv run clockify-mcp --help
uv run pytest -q
uv run ruff check src/ tests/

许可证

MIT