Clockify MCP 服务器

这是一个提供与 Clockify 时间跟踪 API 全面集成的 Model Context Protocol (MCP) 服务器。该服务器通过标准化接口实现自动时间条目管理、项目组织、任务跟踪和报告。

想以故事形式阅读 LinkedIn 文章

快速安装（推荐）

通过 NPM 安装

npm install -g @ratheesh-aot/clockify-mcp-server

配置 Claude Desktop 或任何 MCP 客户端

在您的 MCP 客户端配置中添加以下内容：

{
  "mcpServers": {
    "clockify": {
      "command": "clockify-mcp-server",
      "env": {
        "CLOCKIFY_API_KEY": "your_clockify_api_key"
      }
    }
  }
}

获取您的 Clockify API 密钥

1. 登录到 Clockify
2. 转到个人资料设置 → API
3. 生成或复制您的 API 密钥
4. 将配置中的 your_clockify_api_key 替换为您自己的 API 密钥

开始使用

重启您的 MCP 客户端（Claude Desktop）并开始询问：

• "显示我的 Clockify 工作区"
• "创建一个项目营销的 2 小时时间条目"
• "获取本周的时间条目"

功能

核心功能

• 时间条目管理：创建、读取、更新、删除和停止时间条目
• 项目管理：具有客户关联的项目的完整 CRUD 操作
• 任务管理：在项目内创建和管理任务
• 客户管理：按客户组织工作
• 标签管理：用标签对时间条目进行分类
• 用户及工作区管理：访问用户信息和工作区详情
• 高级报告：生成详细的汇总报告，并带有过滤功能

关键能力

• 实时时间跟踪：启动、停止和管理正在进行的时间条目
• 全面过滤：根据项目、任务、客户、标签和日期范围过滤时间条目
• 分页支持：高效处理大数据集，正确分页
• 灵活报告：生成多种格式的报告（JSON、PDF、CSV、XLSX）
• 生产就绪：错误处理、验证和强大的 API 交互

替代安装（开发）

如果您希望从源码构建或参与开发：

先决条件

• Node.js 18 或更高版本
• 具有 API 访问权限的 Clockify 账户
• Clockify API 密钥

手动安装

1. 克隆仓库：

git clone https://github.com/ratheesh-aot/clockify-mcp.git
cd clockify-mcp

2. 安装依赖项：

npm install

3. 构建 TypeScript 代码：

npm run build

4. 使用完整路径配置：

{
  "mcpServers": {
    "clockify": {
      "command": "node",
      "args": ["/full/path/to/clockify-mcp/dist/index.js"],
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}

可用工具

用户及工作区管理

• get_current_user：获取当前用户信息
• get_workspaces：列出所有可访问的工作区
• get_workspace_users：获取工作区内的所有用户

时间条目管理

• create_time_entry：创建新的时间条目，可选项目/任务关联
• get_time_entries：检索时间条目，带有全面的过滤选项
• update_time_entry：修改现有时间条目
• delete_time_entry：删除时间条目
• stop_time_entry：停止当前运行的时间条目

项目管理

• create_project：创建具有客户关联的新项目
• get_projects：列出项目，带有过滤和分页
• get_project：获取详细的项目信息
• update_project：修改项目详情
• delete_project：删除项目

任务管理

• create_task：在项目内创建任务
• get_tasks：列出任务，带有过滤选项
• get_task：获取详细的任务信息
• update_task：修改任务详情
• delete_task：删除任务

客户管理

• create_client：创建新客户
• get_clients：列出客户，带有过滤
• update_client：修改客户信息
• delete_client：删除客户

标签管理

• create_tag：创建用于分类的新标签
• get_tags：列出可用标签
• update_tag：修改标签详情
• delete_tag：删除标签

报告

• get_detailed_report：生成全面的时间跟踪报告
• get_summary_report：生成带有分组选项的汇总报告

使用示例

创建时间条目

{
  "tool": "create_time_entry",
  "arguments": {
    "workspaceId": "workspace_id",
    "description": "正在实施功能",
    "start": "2024-01-15T09:00:00Z",
    "end": "2024-01-15T17:00:00Z",
    "projectId": "project_id",
    "billable": true
  }
}

带过滤的时间条目

{
  "tool": "get_time_entries",
  "arguments": {
    "workspaceId": "workspace_id",
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z",
    "project": "project_id",
    "page": 1,
    "pageSize": 100
  }
}

创建项目

{
  "tool": "create_project",
  "arguments": {
    "workspaceId": "workspace_id",
    "name": "网站重新设计",
    "clientId": "client_id",
    "billable": true,
    "isPublic": false,
    "color": "#FF5722"
  }
}

故障排除

常见问题

“命令未找到”错误：

# 检查是否正确安装
npm list -g @ratheesh-aot/clockify-mcp-server

# 如需重新安装
npm uninstall -g @ratheesh-aot/clockify-mcp-server
npm install -g @ratheesh-aot/clockify-mcp-server

“无效的 API 密钥”错误：

• 验证您的 Clockify API 密钥是否正确
• 确保 API 密钥具有适当的权限
• 检查是否有额外的空格或字符

MCP 连接问题：

• 重启您的 MCP 客户端（Claude Desktop）
• 验证 JSON 配置是否有效
• 检查 Node.js 是否已安装且可访问

获取帮助

• 问题：GitHub Issues
• 文档：Clockify API 文档
• MCP 协议：Model Context Protocol

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT 许可证 - 详情见 LICENSE 文件。

作者

由 Ratheesh Kumar 创建