AI导哈

时间管理API服务器

Clockify MCP服务器是一个功能丰富的时间管理API集成服务，提供对Clockify工作区的全面CRUD操作，包括工作区、客户、项目、任务、标签和时间跟踪管理。

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

使用说明

Clockify MCP服务器-功能丰富版

用于Clockify API集成的全面MCP（模型上下文协议）服务器，在Clockify的所有主要功能中提供完整的CRUD操作。此服务器使Claude等LLM能够管理您的整个Clockify工作区，从工作区和客户端到项目、任务、标签和时间跟踪。

特性

工作空间管理

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

客户管理

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

项目管理

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

任务管理

  • list任务 -列出项目的任务
  • 创建任务 -创建具有名称、估计值和任务分配的任务
  • 下载中 -更新任务状态、估算、分配
  • 删除任务 -删除任务

标签管理

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

时间录入管理

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

定时器操作

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

总计：33个工具 涵盖所有主要的Clockify运营

快速开始

先决条件

安装

  1. 克隆此存储库：
git clone https://github.com/yourusername/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": ["C:\\Work\\community\\ClockifyTools\\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"
      }
    }
  }
}

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日以来的所有时间条目”

发展

脚本

  • npm run build -将TypeScript编译为JavaScript
  • npm run watch -开发观看模式
  • npm run inspector -使用MCP检查员进行测试
  • npm run lint -抓取代码库
  • npm run lint:fix -自动修复掉毛问题
  • npm test -运行测试（实施时）

项目结构

clockify-mcp/
├── src/
│   ├── index.ts              # MCP server setup (STDIO transport)
│   ├── handlers.ts           # Tool handler routing
│   ├── api/
│   │   ├── client.ts         # Clockify API client wrapper
│   │   ├── 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
│   └── types/
│       └── clockify.ts       # TypeScript interfaces for API
├── build/                    # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

建筑

  • 运输： STDIO（用于克劳德桌面和VSCode集成）
  • 运行时间： Node.js与TypeScript
  • MCP-SDK： @modelcontextprotocol/sdk v0.6.0
  • 身份验证： 通过环境变量的API密钥
  • API Clockify REST API v1(https://api.clockify.me/api/v1)

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 实施。这个功能丰富的版本建立在这个基础上，从只读+基本时间输入功能扩展到所有主要Clockify资源的完整CRUD操作。

最初的实施提供了：

  • 优秀的MCP架构模式
  • 基于Docker的部署
  • 摘要报告功能
  • 用户管理

本版本对其进行了扩展：

  • 客户端、项目、任务和标签的完整CRUD
  • 全面的时间录入管理
  • 定时器操作（启动/停止/激活）
  • 时间输入的批量操作
  • 工作空间配置管理
  • 增强的TypeScript类型安全性
  • 模块化API层架构

看看 原始存储库 基于Docker的部署和CI/CD示例。

相关 MCP