AI导哈

时间追踪集成服务

一个用于Clockify时间追踪集成的MCP服务器，支持管理时间条目、项目、标签、客户、任务等。

  • by skafaliev-dev
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 skafaliev-dev/clockify-mcp-server

使用说明

时钟化MCP服务器

用于Clockify时间跟踪集成的模型上下文协议（MCP）服务器。该服务器使人工智能助手能够与Clockify的API交互，以管理时间条目、项目、标签、客户端、任务等。

特性

  • 工作区：检索工作区信息
  • 项目：创建、读取、更新和删除项目
  • 时间条目：使用完整的CRUD操作跟踪时间
  • 标签：用标签组织时间条目
  • 客户：管理客户信息
  • 任务：在项目中创建和管理任务
  • 用户：检索用户信息
  • 报告：生成时间跟踪报告

使用Docker运行

您可以在Docker容器中运行MCP服务器：

docker build -t clockify-mcp-server .
docker run --env CLOCKIFY_API_KEY=your_api_key_here -p 3000:3000 clockify-mcp-server

您还可以根据需要传递其他环境变量（请参阅配置部分）。

先决条件

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

安装

  1. 克隆或下载此存储库

  2. 安装依赖项：


### Running Tests

To run the test suite:

```bash
npm test

npm安装


3. Set up your environment variables (see Configuration below)

This project is licensed under the terms of the MIT license. See the [LICENSE](./LICENSE) file for details.

## Configuration


1. Log in to Clockify
2. Go to Settings → Advanced → Manage API keys
3. Copy your API key

### Environment Variables

Set the following environment variables:

```bash
CLOCKIFY_API_KEY=your_api_key_here
CLOCKIFY_API_BASE_URL=https://api.clockify.me/api/v1  # Optional, defaults to this value

区域URL （如果您使用的是区域实例）：

  • 欧盟： https://euc1.clockify.me/api/v1
  • 我们： https://use2.clockify.me/api/v1
  • 英国： https://euw2.clockify.me/api/v1
  • AU： https://apse2.clockify.me/api/v1

发展

项目结构

mcp/
├── src/
│   ├── server.js           # Main MCP server implementation
│   └── clockify-api.js     # Clockify API client wrapper
├── test/
│   └── clockify-api.test.js # Basic tests for Clockify API client
├── package.json            # Project dependencies and scripts
├── clockify-mcp-spec.json  # API specification
├── .env.example            # Example environment variables
├── .github/
│   └── workflows/
│       └── build.yml       # CI workflow
├── eslint.config.js        # ESLint configuration
└── README.md               # This file

用法

运行服务器

npm start

对于自动重新加载的开发：

npm run dev

与Claude Desktop一起使用

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

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "clockify": {
      "command": "node",
      "args": ["<path-to-your-server.js>"],
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}

与其他MCP客户端一起使用

服务器通过stdio进行通信，并遵循模型上下文协议规范。配置您的MCP客户端以运行：

node server.js

设置适当的环境变量。

可用工具

工作区工具

  • get_workspaces -获取所有可访问的工作区
  • get_workspace -获取特定工作空间的详细信息

项目工具

  • get_projects -列出工作区中的项目
  • get_project -获取项目详细信息
  • create_project -创建新项目
  • update_project -更新项目详细信息
  • delete_project -删除项目

时间输入工具

  • get_time_entries -列出时间条目
  • create_time_entry -创建新的时间条目
  • update_time_entry -更新时间条目
  • delete_time_entry -删除时间条目
  • start_time_entry -启动运行计时器
  • stop_time_entry -停止当前计时器
  • get_running_time_entry -获取当前运行时间条目

标记工具

  • get_tags -列出工作区中的标签
  • create_tag -创建新标签

客户端工具

  • get_clients -在工作区中列出客户端
  • create_client -创建新客户端

任务工具

  • get_tasks -列出项目中的任务
  • create_task -创建新任务

用户工具

  • get_current_user -获取经过身份验证的用户详细信息
  • get_users -列出工作区中的用户

报告工具

  • get_reports -生成时间跟踪报告

示例用法

启动计时器

{
  "tool": "start_time_entry",
  "arguments": {
    "workspaceId": "your_workspace_id",
    "description": "Working on documentation",
    "projectId": "your_project_id",
    "tagIds": ["tag_id_1", "tag_id_2"],
    "billable": true
  }
}

创建项目

{
  "tool": "create_project",
  "arguments": {
    "workspaceId": "your_workspace_id",
    "name": "New Project",
    "clientId": "client_id",
    "color": "#FF5733",
    "billable": true
  }
}

获取时间条目

{
  "tool": "get_time_entries",
  "arguments": {
    "workspaceId": "your_workspace_id",
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z",
    "projectId": "your_project_id"
  }
}

API费率限制

Clockify API的速率限制为 每秒50个请求 每个插件在一个工作区上。服务器当前没有实现速率限制，因此在发出请求时请注意这一点。

资源

服务器公开以下资源：

  • clockify://workspaces -所有工作区列表

错误处理

服务器处理Clockify API的错误，并以结构化格式返回错误。常见错误包括：

  • API密钥丢失或无效
  • 工作区/项目/标记ID无效
  • 请求频率超限
  • 权限不足

发展

项目结构

mcp/
├── server.js              # Main MCP server implementation
├── clockify-api.js        # Clockify API client wrapper
├── package.json           # Project dependencies
├── clockify-mcp-spec.json # API specification
└── README.md             # This file

添加新工具

  1. 在中添加工具定义 ListToolsRequestSchema 处理器
  2. 在中实现API方法 clockify-api.js 如有需要
  3. 在中添加工具处理程序案例 CallToolRequestSchema 处理器

故障排除

“需要CLOCKIFY_API_KEY环境变量”

  • 确保您已设置 CLOCKIFY_API_KEY 环境变量
  • 检查您的MCP客户端配置是否包含env变量

API错误

  • 在Clockify设置中验证您的API密钥是否有效
  • 检查您是否使用了正确的工作区/项目ID
  • 确保您在Clockify中拥有必要的权限

连接问题

  • 如果适用，请验证您使用的是正确的API区域URL
  • 检查您的互联网连接
  • 确保Clockify服务正常运行

贡献

欢迎投稿！请随时提交问题或拉取请求。

许可证

麻省理工学院

相关链接

支持

关于以下问题：

  • 此MCP服务器：在此存储库中打开一个问题
  • Clockify API：联系Clockify支持
  • MCP协议：检查MCP文档

相关 MCP