AI导哈

Clockify API集成服务器

一个全面的Clockify API集成服务器，提供83种工具用于时间跟踪、项目管理、报告生成等全功能CRUD操作。

  • by JorgeDiazz
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 JorgeDiazz/clockify-mcp

使用说明

时钟化MCP服务器

用于Clockify API集成的全面MCP（模型上下文协议）服务器，提供 83工具 用于所有主要Clockify功能的完整CRUD操作。此服务器使Claude等LLM能够管理您的整个Clockify工作区——从时间跟踪和项目到发票、日程安排和报告。

特性

工作空间管理

  • list工作区 -列出所有可访问的工作区
  • 获取工作区 -获取工作区详细信息
  • updateWorkspace -更新工作区设置

客户管理

  • 客户列表 -列出具有过滤功能的客户端（存档、名称、分页）
  • 创建客户端 -创建新客户端
  • updateClient -更新客户详细信息，存档/取消存档
  • deleteClient -删除客户端

项目管理

  • 项目列表 -列出具有筛选功能的项目（存档、名称、客户端、分页）
  • getProject -获取单个项目详细信息
  • 创建项目 -使用客户端、颜色、计费设置创建新项目
  • updateProject -更新项目详细信息、预算、时间估算
  • 删除项目 -删除/存档项目

任务管理

  • list任务 -列出项目的任务（带分页）
  • getTask -获取特定任务的详细信息
  • 创建任务 -创建具有名称、估计值和任务分配的任务
  • 下载中 -更新任务状态、估算、分配
  • 删除任务 -删除任务

标签管理

  • 列表标签 -列出工作区中的标签（带分页）
  • 创建标签 -创建新标签
  • %剩下的 -更新标记名称，存档/取消存档
  • 删除标签 -删除标签

时间录入管理

  • listTimeEntries -列出具有筛选功能的时间条目（日期范围、项目、任务、标签、分页）
  • getTimeEntry -获取特定时间输入详细信息
  • createTimeEntry -创建已完成的时间条目
  • 更新时间条目 -更新现有时间条目
  • deleteTimeEntry -删除时间条目
  • bulkUpdateTimeEntries -一次更新多个时间条目
  • bulkDeleteTimeEntries -一次删除多个时间条目

定时器操作

  • 开始计时器 -启动新的运行计时器
  • stopTimer -停止当前正在运行的计时器
  • getActiveTimer -获取当前运行计时器（如果有）

用户管理

  • 获取当前用户 -获取当前经过身份验证的用户信息
  • list工作区用户 -列出工作区中的所有用户（带分页）

用户组管理

  • 列表用户组 -列出用户组（带分页）
  • getUserGroup -获取特定用户组
  • 创建用户组 -创建新用户组
  • 更新用户组 -更新用户组
  • deleteUserGroup -删除用户组
  • addUserToGroup -将用户添加到组
  • 从组中删除用户 -从组中删除用户

报告

  • 获取摘要报告 -生成摘要报告
  • 获取详细报告 -生成详细报告
  • getWeeklyReport -生成周报

共享报告

  • listSharedReports -列出共享报告（带分页）
  • 获取共享报告 -获取特定的共享报告
  • 创建共享报告 -创建新的共享报告
  • 已更新SharedReport -更新共享报告
  • 删除共享报告 -删除共享报告

发票管理（付费功能）

  • 清单发票 -列出带有状态过滤器的发票（带分页）
  • getInvoice -获取具体发票
  • 创建发票 -创建新发票
  • 更新发票 -更新发票
  • 删除发票 -删除发票

费用管理（付费功能）

  • 费用清单 -列出费用（带页码）
  • 列表费用类别 -列出费用类别（带页码）
  • get费用 -获取具体费用
  • createExpense -创建新支出
  • update费用 -更新费用
  • 删除费用 -删除费用

休假管理（付费功能）

  • listTimeOff请求 -使用状态过滤器（带分页）列出休假请求
  • listTimeOff政策 -列出休假政策（带页码）
  • getTimeOffRequest -获取特定的休假请求
  • createTimeOff请求 -创建新的休假请求
  • updateTimeOff请求 -更新休假请求
  • deleteTimeOff请求 -删除休假请求

审批管理（付费功能）

  • list审批请求 -列出带有状态过滤器的审批请求（带分页）
  • 提交以供批准 -提交时间条目以供审批
  • updateApprovalRequest -批准/拒绝批准请求

日程安排（付费功能）

  • list任务 -列出日程安排任务（带分页）
  • getAssignment -获得特定任务
  • createAssignment -创建新任务
  • updateAssignment -更新作业
  • deleteAssignment -删除作业

自定义字段

  • listCustomFields -列出自定义字段（带分页）
  • Getcustomfield -获取特定的自定义字段
  • createCustomField -创建新的自定义字段
  • 更新自定义字段 -更新自定义字段
  • deleteCustomField -删除自定义字段

网络钩子

  • listWebhooks -列出Webhook（带分页）
  • getWebhook -获取特定的webhook
  • createWebhook -创建新的webhook
  • updateWebhook -更新webhook
  • deleteWebhook -删除webhook

总计：83个工具 跨越18个API模块，提供完整的分页支持。

快速开始

先决条件

安装

  1. 克隆此存储库：
git clone https://github.com/JorgeDiazz/clockify-mcp.git
cd clockify-mcp
  1. 安装依赖项：
npm install
  1. 构建项目：
npm run build

配置

适用于克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "clockify": {
      "command": "node",
      "args": ["/absolute/path/to/clockify-mcp/build/index.js"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

适用于带MCP扩展的VSCode

添加到VSCode MCP设置中：

{
  "mcpServers": {
    "clockify": {
      "command": "node",
      "args": ["/absolute/path/to/clockify-mcp/build/index.js"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

通过NPX（无需克隆）

{
  "mcpServers": {
    "clockify": {
      "command": "npx",
      "args": ["@jeremyvyska/clockify-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

MCP检验员测试

在与Claude集成之前测试服务器：

npm run inspector

这将启动MCP Inspector UI，您可以在其中交互式地测试所有工具。

如何获取Clockify API密钥

  1. 登录到您的 时钟化帐户
  2. 点击您的个人资料图标（右上角）→ 配置文件设置
  3. 滚动到 API 部分
  4. 点击 生成 创建新的API密钥，或复制现有密钥

使用示例

配置后，您可以向Claude询问以下问题：

工作区设置：

  • “列出我的所有Clockify工作区”
  • “创建一个名为‘Acme Corp’的新客户，地址为‘主街123号’”
  • “为客户Acme Corp创建一个‘网站重新设计’项目”

任务管理：

  • “将“设计主页模型”任务添加到网站重新设计项目中”
  • “列出网站重新设计项目的所有活动任务”
  • “将主页原型任务标记为已完成”

时间跟踪：

  • “为网站重新设计项目启动计时器”
  • “我的活动计时器是什么？”
  • “停止我的计时器”
  • “显示我今天的时间条目”
  • “在网站重新设计项目中为昨天创建一个2小时的时间条目”

批量操作：

  • “将我上周的所有时间条目更改为网站重新设计项目”
  • “删除12月1日以来的所有时间条目”

报告：

  • “生成上周的摘要报告”
  • “向我展示网站重新设计项目的详细报告”

分页：

  • “列出客户端的第二页，每页10个”
  • “显示状态为已付款的发票，第3页”

发展

脚本

  • npm run build -将TypeScript编译为JavaScript
  • npm run watch -开发观看模式
  • npm test -运行Vitest测试套件
  • npm run lint -抓取代码库
  • npm run lint:fix -自动修复掉毛问题
  • npm run inspector -使用MCP检查员进行测试
  • npm run test:create -在Clockify中创建测试资源（需要 CLOCKIFY_API_KEY)
  • npm run test:cleanup -删除上面创建的测试资源

项目结构

clockify-mcp/
├── src/
│   ├── index.ts              # MCP server setup (STDIO transport)
│   ├── handlers.ts           # Tool schemas + handler routing (83 tools)
│   ├── handlers.test.ts      # Handler tests
│   ├── api/
│   │   ├── client.ts         # Clockify API client wrapper (clockifyFetch)
│   │   ├── workspaces.ts     # Workspace operations
│   │   ├── clients.ts        # Client CRUD
│   │   ├── projects.ts       # Project CRUD
│   │   ├── tasks.ts          # Task CRUD
│   │   ├── tags.ts           # Tag CRUD
│   │   ├── timeEntries.ts    # Time entry operations
│   │   ├── timer.ts          # Timer start/stop
│   │   ├── users.ts          # User operations
│   │   ├── userGroups.ts     # User group CRUD
│   │   ├── reports.ts        # Summary/detailed/weekly reports
│   │   ├── sharedReports.ts  # Shared report CRUD
│   │   ├── invoices.ts       # Invoice CRUD
│   │   ├── expenses.ts       # Expense + category CRUD
│   │   ├── timeOff.ts        # Time-off requests + policies
│   │   ├── approvals.ts      # Approval request operations
│   │   ├── scheduling.ts     # Assignment CRUD
│   │   ├── customFields.ts   # Custom field CRUD
│   │   └── webhooks.ts       # Webhook CRUD
│   └── types/
│       └── clockify.ts       # TypeScript interfaces for API models
├── build/                    # Compiled JavaScript (generated)
├── vitest.config.ts          # Test configuration
├── eslint.config.js          # ESLint + Prettier configuration
├── tsconfig.json
├── CLAUDE.md                 # AI assistant instructions
└── README.md

建筑

  • 运输： STDIO（用于克劳德桌面和VSCode集成）
  • 运行时间： Node.js 20+与TypeScript
  • MCP-SDK： @modelcontextprotocol/sdk ^1.26.0
  • 身份验证： API密钥通过 CLOCKIFY_API_KEY 环境变量
  • API Clockify REST API v1(https://api.clockify.me/api/v1)
  • 分页： 所有列表端点支持 page （1-索引）和 pageSize （默认50个）参数

API费率限制

Clockify API的速率限制为 每秒50个请求。此服务器中的批量操作可帮助您在执行批量更新时保持此限制。

故障排除

服务器未出现在Claude Desktop中：

  1. 检查配置中的路径是否是绝对的，而不是相对的
  2. 验证 CLOCKIFY_API_KEY 环境变量已设置
  3. 完全重新启动克劳德桌面
  4. 检查Claude Desktop日志是否有错误

“未知工具”错误：

  • 跑 npm run build 确保编译最新代码
  • 验证您是否使用了正确的工作区ID（使用 listWorkspaces 第一）

身份验证错误：

  • 验证您的API密钥是否有效（在https://api.clockify.me/api/v1/user随着 X-Api-Key 头球
  • 检查API密钥在您的工作区中是否具有必要的权限

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 通过测试进行更改
  4. 提交拉取请求

许可证

MIT许可证-请参阅 许可证 详细信息文件

致谢

非常感谢。 到 @印度 对于原件 时钟化mcp 实施和 @杰瑞米 为了 功能丰富的版本 这将其扩展到完整的CRUD操作。这个fork建立在这两者之上，增加了对所有列表端点的分页支持、额外的API模块和全面的测试套件。

相关 MCP