内容
# clockify-mcp
[](https://github.com/tracegazer/clockify-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/clockify-mcp/)
[](https://pypi.org/project/clockify-mcp/)
[](LICENSE)
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.tracegazer/clockify-mcp)
[](https://smithery.ai/servers/tracegazer/clockify-mcp)
<!-- mcp-name: io.github.tracegazer/clockify-mcp -->
> 一个适用于 **Clockify** 时间跟踪 API 的模型上下文协议（MCP）服务器。
给你的 AI 助手提供访问你的 Clockify 数据的能力 - 查询工作区、项目和时间记录，生成报告，记录小时数，管理客户、发票等 - 所有操作都可以通过自然语言进行。
**112 个工具**，涵盖 18 个领域。默认情况下为只读，可选写操作需要显式确认。
## 一键安装
使用 **Claude Desktop** （和其他兼容 MCPB 的客户端）最简单的方法是使用预构建的软件包：
**➡️ [下载 `clockify-mcp.mcpb`](https://github.com/tracegazer/clockify-mcp/releases/latest/download/clockify-mcp.mcpb)** - 然后双击它。Claude Desktop 会打开安装程序，提示输入你的 Clockify API 密钥，然后完成安装。无需 Python，无需 `npx`/`uvx`，无需配置文件。
`.mcpb` 文件附在每个 [GitHub Release](https://github.com/tracegazer/clockify-mcp/releases) 中，并在 [Smithery](https://smithery.ai/) 上镜像。如果你更喜欢包管理器或容器，请参见下面的 [快速入门](#快速入门)。
## 功能
**48 个只读工具** 目前可用（阶段 0-8b - 18 个领域）。64 个写工具（跨客户端、项目、任务、标签、时间记录、假期、费用和费用类别、时间请假策略/请求管理、审批提交/重新提交/更新、自定义字段创建/更新/删除和项目分配、调度分配管理、发票和付款管理、共享报告管理以及 webhook 创建/更新/删除令牌）在你设置 `CLOCKIFY_ACCESS_MODE=full` （或后兼容 `CLOCKIFY_ENABLE_WRITES=true`）时注册。中等 `time-tracking` 模式仅暴露时间记录写入用于记录小时数 - 请参见 [访问模式](#配置)。
| 领域 | 工具 | 工具名称 |
|--------|------:|------------|
| **工作区** | 3 | `get_current_user`，`list_workspaces`，`get_workspace` |
| **用户** | 3 | `list_users`，`get_user_member_profile`，`find_user_team_manager` |
| **组** | 1 | `list_user_groups` |
| **客户** | 2 | `list_clients`，`get_client` |
| **项目** | 2 | `list_projects`，`get_project` |
| **任务** | 2 | `list_tasks`，`get_task` |
| **标签** | 2 | `list_tags`，`get_tag` |
| **时间记录** | 2 | `list_time_entries`，`get_time_entry` |
| **报告** | 6 | `generate_detailed_report`，`generate_summary_report`，`generate_weekly_report`，`generate_attendance_report`‡，`generate_expense_report`‡，`export_report` （PDF/CSV/XLSX 到文件） |
| **共享报告** | 2 | `list_shared_reports`，`get_shared_report` |
| **请假**† | 5 | `list_time_off_policies`，`get_time_off_policy`，`list_time_off_balances_by_policy`，`list_time_off_balances_by_user`，`list_time_off_requests` |
| **假期**† | 2 | `list_holidays`，`list_holidays_in_period` |
| **费用**† | 4 | `list_expenses`，`get_expense`，`list_expense_categories`，`download_expense_receipt` |
| **审批**† | 1 | `list_approval_requests` |
| **自定义字段**† | 2 | `list_workspace_custom_fields`，`list_project_custom_fields` |
| **调度**† | 3 | `list_scheduled_assignments`，`get_project_scheduling_totals`，`get_user_scheduling_totals` |
| **发票**† | 3 | `list_invoices`，`get_invoice`，`get_invoice_payments` |
| **Webhook**† | 3 | `list_webhooks`，`get_webhook`，`get_webhook_logs` |
† **请假**，**假期**，**费用**，**审批**，**自定义字段**，**调度**，**发票** 和 **Webhook** 是付费的 Clockify 功能 - 这些工具在没有这些功能的计划上会出错（HTTP 402/403/404）。
‡ `generate_attendance_report` 和 `generate_expense_report` （以及这两个类型的 `export_report`）需要工作区的出勤/费用插件；基于时间的报告（详细/摘要/每周）和共享报告在免费计划上有效。
**写工具** （需要确认 - 设置 `CLOCKIFY_ACCESS_MODE=full`）：
| 领域 | 工具 | 工具名称 |
|--------|------:|------------|
| **客户** | 3 | `create_client`，`update_client`，`delete_client` |
| **项目** | 3 | `create_project`，`update_project`，`delete_project` |
| **任务** | 3 | `create_task`，`update_task`，`delete_task` |
| **标签** | 3 | `create_tag`，`update_tag`，`delete_tag` |
| **时间记录** | 7 | `create_time_entry`，`update_time_entry`，`delete_time_entry`，`duplicate_time_entry`，`bulk_update_time_entries`，`create_time_entry_for_user`，`stop_running_timer` |
| **共享报告** | 3 | `create_shared_report`，`update_shared_report`，`delete_shared_report` |
| **请假**† | 5 | `create_time_off_policy`，`create_time_off_request`，`approve_time_off_request`，`reject_time_off_request`，`withdraw_time_off_request` |
| **假期**† | 3 | `create_holiday`，`update_holiday`，`delete_holiday` |
| **费用**† | 7 | `create_expense`，`update_expense`，`delete_expense`，`create_expense_category`，`update_expense_category`，`delete_expense_category`，`archive_expense_category` |
| **审批**† | 4 | `submit_approval_request`，`submit_approval_request_for_user`，`resubmit_approval_entries`，`update_approval_request` |
| **自定义字段**† | 5 | `create_workspace_custom_field`，`update_workspace_custom_field`，`delete_workspace_custom_field`，`set_project_custom_field`，`remove_project_custom_field` |
| **调度**† | 5 | `create_scheduled_assignment`，`update_scheduled_assignment`，`delete_scheduled_assignment`，`publish_scheduled_assignment`，`copy_scheduled_assignment` |
| **发票**† | 9 | `create_invoice`，`update_invoice`，`change_invoice_status`，`duplicate_invoice`，`delete_invoice`，`create_invoice_item`，`update_invoice_item`，`delete_invoice_item`，`create_invoice_payment` |
| **Webhook**† | 4 | `create_webhook`，`update_webhook`，`delete_webhook`，`generate_webhook_token` |
† **请假**，**假期**，**费用**，**审批**，**自定义字段**，**调度**，**发票** 和 **Webhook** 是付费的 Clockify 功能 - 这些工具在没有这些功能的计划上会出错（HTTP 402/403/404）。
`create_expense` 和 `update_expense` 接受一个可选的本地收据文件，通过多部分上传。
## 快速入门
### 1. 安装
```bash
pip install clockify-mcp
```
或在不安装的情况下运行（需要 [uv](https://docs.astral.sh/uv/)）：
```bash
uvx clockify-mcp
```
或使用容器镜像（每次发布都发布到 GHCR）：
```bash
docker run --rm -i -e CLOCKIFY_API_KEY=your-key ghcr.io/tracegazer/clockify-mcp:latest
```
### 2. 连接到 Claude Desktop
将以下内容添加到你的 `claude_desktop_config.json` 中：
```jsonc
{
"mcpServers": {
"clockify": {
"command": "uvx",
"args": ["clockify-mcp"],
"env": {
"CLOCKIFY_API_KEY": "your-api-key"
}
}
}
}
```
重启 Claude Desktop。询问：_我有哪些工作区在 Clockify 中？_
<details>
<summary>使用 pip 安装而不是 uvx</summary>
```jsonc
{
"mcpServers": {
"clockify": {
"command": "clockify-mcp",
"env": {
"CLOCKIFY_API_KEY": "your-api-key"
}
}
}
}
```
</details>
<details>
<summary>启用写入操作</summary>
默认情况下，服务器 **只读**。通过 `CLOCKIFY_ACCESS_MODE` 选择写入：
| 模式 | 读取 | 写入 |
|------|------------|--------|
| `read` （默认）| 所有内容 | 无 |
| `time-tracking` | 所有内容 | 仅时间记录写入（记录和编辑小时数） |
| `full` | 所有内容 | 所有写入工具（客户端、项目、发票等） |
```jsonc
{
"mcpServers": {
"clockify": {
"command": "uvx",
"args": ["clockify-mcp"],
"env": {
"CLOCKIFY_API_KEY": "your-api-key",
"CLOCKIFY_ACCESS_MODE": "full"
}
}
}
}
```
> **兼容性：** 旧版 `CLOCKIFY_ENABLE_WRITES=true` 仍然有效，映射到 `full`。如果两者都设置，则 `CLOCKIFY_ACCESS_MODE` 优先。在 `time-tracking` 模式下，`duplicate`/`bulk` 始终对已认证用户生效；对于 `update`/`delete` 按 ID，助手会被告知在触摸可能属于其他用户的条目之前进行确认。
> **警告：** 写入模式允许连接的代理通过你的 Clockify 凭证创建、修改和删除真实数据。`delete_*` 工具和 `withdraw_time_off_request` 是不可逆的。
</details>
### 3. 获取你的 API 密钥
登录 Clockify → **个人资料设置** → **API** → 复制你的 API 密钥。
## 配置
配置按以下顺序解析（优先级最高）：
1. **环境变量** （始终获胜）
2. **TOML 配置文件** 在 `~/.config/clockify-mcp/config.toml`
| 环境变量 | TOML 键 | 描述 |
|---------|----------|-------------|
| `CLOCKIFY_API_KEY` | `api_key` | 你的 Clockify API 密钥（必填） |
| `CLOCKIFY_REGION` | `region` | `global` （默认）\| `euc1` （欧盟）\| `use2` （美国）\| `euw2` （英国）\| `apse2` （澳大利亚） |
| `CLOCKIFY_BASE_URL` | `base_url` | 子域工作区的覆盖，例如 `https://acme.clockify.me` |
| `CLOCKIFY_DEFAULT_WORKSPACE_ID` | `default_workspace_id` | 工具调用省略 `workspace_id` 时的备用工作区 |
| `CLOCKIFY_ACCESS_MODE` | `access_mode` | `read` （默认）\| `time-tracking` （读取 + 记录小时数）\| `full` （所有写入） |
| `CLOCKIFY_ENABLE_WRITES` | `enable_writes` | 兼容别名：`true` = `access_mode=full`。`CLOCKIFY_ACCESS_MODE` 优先。 |
| `CLOCKIFY_TELEMETRY` | `telemetry_enabled` | 启用 OpenTelemetry - 默认 `false` |
| `CLOCKIFY_TELEMETRY_DETAIL` | `telemetry_detail` | 跨度详细信息：`metadata` （默认），`ids` 或 `full` |
**访问模式：** `read` 仅暴露读取工具。`time-tracking` 添加时间记录写入工具（创建/更新/删除/复制/批量）用于记录小时数，等等。`full` 暴露所有写入工具。这控制服务器注册哪些 MCP 工具；它不是 API 密钥自身权限的替代品。
参见 [`config.toml.example`](config.toml.example) 获取复制粘贴模板。
```toml
# ~/.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`
## 运行服务器
```bash
clockify-mcp # STDIO 传输（默认）
clockify-mcp --transport sse # SSE/HTTP 传输
```
> **安全注意：** 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 调用）。
## 付费功能及在 Clockify 中启用它们
许多领域受到 **两个** 独立因素的限制 - 两个因素都必须为真，工具才能工作：
**1. 工作区计划必须包含该功能。** 否则，API 返回 `402` （或“订阅”消息），服务器引发 `ClockifyAPIError`，类别为 `PLAN_REQUIRED`。
| 功能 | 最低计划 |
|---------|--------------|
| 报告（详细/摘要/每周），共享报告 | 免费 |
| Webhook | 免费（最多 3 个）- 付费更多 |
| 请假，假期，发票，审批 | 标准 |
| 费用（包括费用报告），自定义字段，调度 | 专业版 |
| 出勤报告 | 专业版（出勤/时间跟踪插件） |
**2. 必须在工作区中启用该模块。** 即使在正确的计划中，管理员也必须在 Clockify → **工作区设置** 中启用这些：**请假**，**费用**，**审批**，**发票**，**调度**。在启用之前，API 返回 `403 "Access Denied"`，服务器引发 `ClockifyAPIError`，类别为 `ACCESS_DENIED`。（自定义字段，Webhook 和报告不需要单独切换。）
当操作失败时，错误类别指示要执行的操作：
- `PLAN_REQUIRED` - 升级工作区计划（标准/专业版）。
- `ACCESS_DENIED` - 在工作区设置中启用该功能，或检查 API 密钥用户的角色/权限。
- `AUTH` - API 密钥丢失、无效或已撤销。
## 可观察性（可选）
服务器可以发出 OpenTelemetry 跟踪、指标和日志 - 完全可选且供应商中立。导出到任何 OTLP 兼容的后端（Dynatrace、Grafana、Datadog、Jaeger 等）。当禁用时，`opentelemetry` 永远不会被导入。
```bash
pip install "clockify-mcp[telemetry]"
export CLOCKIFY_TELEMETRY=1
```
OTLP 端点和标头通过标准 OpenTelemetry 环境变量配置（不在 TOML 文件中）。`CLOCKIFY_TELEMETRY_DETAIL` 控制附加多少参数/有效负载数据（`metadata` 默认 → `ids` → `full`）；始终会删除 API 密钥。
<details>
<summary>Dynatrace 设置</summary>
```bash
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
```
所需的令牌范围：`openTelemetryTrace.ingest`，`metrics.ingest`，`logs.ingest`。Dynatrace 的 OTLP 指标摄取需要 **delta** 时间性 - 如果没有环境变量，指标导出将失败，返回 `400 Bad Request`。
</details>
<details>
<summary>通用 OTLP 收集器</summary>
```bash
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_SERVICE_NAME=clockify-mcp
```
</details>
**发出的信号：
- **跟踪** - 每个 MCP 工具调用 (`execute_tool <name>`) 和每个 Clockify API 请求的跨度
- **指标** - `mcp.tool.duration`，`mcp.tool.errors` 和 Clockify 客户端请求持续时间
- **日志** - 工具错误和意外的 API 响应形状，与跟踪相关（仅 OTLP，不输出到标准输出）
## 开发
```bash
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](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器