使用说明

时钟化MCP服务器

模型上下文协议（MCP）服务器，提供与Clockify时间跟踪API的无缝集成。该服务器使AI助手能够与Clockify交互，以管理时间条目、项目、任务和工作区。

特性

🕐 时间录入管理：创建、更新、删除和列出时间条目
📁 项目管理：跨工作区浏览和搜索项目
✅ 任务管理：访问和管理项目中的任务
👤 用户档案：检索用户信息和工作区详细信息
🏢 工作空间管理：列出工作区并在工作区之间导航

示范

可用工具

用户管理

get-clockify-user -检索当前用户配置文件信息

工作空间管理

list-clockify-workspaces -列出所有可访问的工作区

项目管理

list-clockify-projects -使用可选名称筛选列出工作区中的项目

任务管理

list-clockify-tasks -列出特定项目中的任务

时间录入管理

create-clockify-time-entry -创建新的时间条目
update-clockify-time-entry -更新现有时间条目
delete-clockify-time-entry -删除时间条目
list-clockify-time-entries -列出带有日期过滤的时间条目

先决条件

为帐户设置时钟：您需要一个具有API访问权限的Clockify帐户
API密钥：从您的个人资料设置生成Clockify API密钥
MCP兼容客户端：使用GitHub Copilot、Claude Desktop或其他MCP客户端进行VS代码

安装

选项1：使用NPX（推荐）

将以下配置添加到MCP客户端：

{
  "servers": {
    "mcp_clockify": {
      "command": "npx",
      "args": ["-y", "mcp_clockify@latest"],
      "env": {
        "CLOCKIFY_API_KEY": "your-clockify-api-key-here"
      }
    }
  }
}

方案2：地方发展

克隆存储库:

git clone <repository-url>
cd clockify-mcp

安装依赖项:
```
npm install
```
构建项目:
```
npm run build
```

配置您的MCP客户端:

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

配置

获取Clockify API密钥

登录您的Clockify帐户
首选 配置文件设置 （点击右上角的头像）
导航到 API 部分
生成或复制现有API密钥

VS代码设置

打开VS代码
运行命令 MCP: Open User Configuration （Ctrl/Cmd+Shift+P）
这将打开或创建 mcp.json 用户配置文件中的文件
使用API密钥添加配置：

{
  "servers": {
    "mcp_clockify": {
      "command": "npx",
      "args": ["-y", "mcp_clockify@latest"],
      "env": {
        "CLOCKIFY_API_KEY": "your-clockify-api-key-here"
      }
    }
  }
}

保存文件并重新启动VS Code

反重力设置

开放反重力
运行命令 Antigravity: Manage MCP Servers （Ctrl/Cmd+Shift+P）
查看原始配置文件
使用API密钥添加配置：

{
  "mcpServers": {
    ...
    "mcp_clockify": {
      "command": "npx",
      "args": ["-y", "mcp_clockify@latest"],
      "env": {
        "CLOCKIFY_API_KEY": "your-clockify-api-key-here"
      }
    }
  }
}

保存文件并重新启动Antigravity

Claude桌面设置

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

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

{
  "mcpServers": {
    "mcp_clockify": {
      "command": "npx",
      "args": ["-y", "mcp_clockify@latest"],
      "env": {
        "CLOCKIFY_API_KEY": "your-clockify-api-key-here"
      }
    }
  }
}

Gemini CLI设置

打开Gemini CLI配置文件（例如。， ~/.gemini/settings.json).
添加以下配置：

{
  "mcpServers": {
    "mcp_clockify": {
      "command": "npx",
      "args": ["-y", "mcp_clockify@latest"],
      "env": {
        "CLOCKIFY_API_KEY": "your-clockify-api-key-here"
      }
    }
  }
}

使用示例

创建时间条目

I worked on the Research project for Acme Corp workspace from today 9 AM to 5 PM. Please create a time entry for this work session in Clockify.

列出最近的时间条目

Show me my time entries for this week in Clockify.

管理项目

List all projects in my main workspace and help me find the "Website Redesign" project.

每日时间追踪

I need to log 3 hours of work on the Mobile App project from 2 PM to 5 PM today with the description "Bug fixes and testing".

发展

脚本

npm run build -构建TypeScript项目
npm start -启动服务器
npm run inspect -使用MCP检查器进行调试

项目结构

├── src/
│   └── index.ts          # Main server implementation
├── build/
│   └── index.js          # Compiled JavaScript
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md             # This file

故障排除

常见问题

无效的API密钥错误
- 验证您的API密钥是否正确并具有正确的权限
- 检查环境变量是否设置正确
网络连接问题
- 确保您有互联网连接
- 验证Clockify API是否可以从您的网络访问
服务器未启动
- 检查是否安装了Node.js（版本16或更高）
- 验证所有依赖项是否已安装 npm install

调试模式

使用MCP检查器进行调试：

npm run inspect

这将打开一个web界面来测试和调试MCP服务器。

API 参考

服务器与Clockify API v1。有关API的详细文档，请访问 Clockify API文档.

贡献

克隆该仓库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

许可证

该项目根据ISC许可证获得许可。

支持

对于问题和疑问：

检查故障排除部分
审查 Clockify API文档
在存储库上打开问题