AI导哈

时间追踪MCP服务器

一个基于TypeScript的模型上下文协议(MCP)服务器，集成Clockodo时间追踪API，提供对用户、时间条目和项目的标准化访问。

  • by inevs
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 inevs/clockodo-mcp

使用说明

Clockodo MCP服务器

一个基于类型脚本的模型上下文协议（MCP）服务器，与Clockodo时间跟踪API集成。此服务器通过标准化的MCP协议提供对Clockodo数据的全面访问，使Claude Desktop和其他MCP客户端能够与Clockodo实例中的用户、时间条目和项目进行交互。

特性

  • 用户资源：从Clockodo实例访问所有注册用户
  • 条目资源：检索日期范围内特定用户的时间条目
  • 项目资源：获取所有项目的详细信息，包括预算和状态
  • 自动分页：自动处理多页数据
  • 实时数据：从Clockodo API获取实时数据
  • 综合录井：用于调试的详细API请求/响应日志记录
  • 类型安全：带Zod验证的完整TypeScript实现
  • 符合MCP标准：遵循模型上下文协议标准，实现无缝集成

先决条件

  • Node.js（v18或更高版本）
  • npm或纱线
  • 具有API访问权限的Clockodo帐户
  • Clockodo API凭据（电子邮件和API密钥）

安装

  1. 克隆存储库：
git clone <repository-url>
cd clockodo-ts
  1. 安装依赖项：
npm install
  1. 创建环境文件：
cp .env.example .env

  1. 在中配置您的Clockodo凭据 .env （参见 配置)

  2. 构建项目：

npm run build

配置

创建一个 .env 使用Clockodo凭据在项目根目录中创建文件：

CLOCKODO_EMAIL=your-email@example.com
CLOCKODO_API_KEY=your-api-key-here

正在获取Clockodo API凭据

  1. 登录您的Clockodo帐户
  2. 转到“设置”→ API
  3. 生成或复制API密钥
  4. 使用您的Clockodo登录电子邮件作为 CLOCKODO_EMAIL

用法

发展模式

对于使用实时TypeScript编译的开发：

npm run dev

生产模式

构建并运行编译后的服务器：

npm run build
node build/index.js

MCP客户端集成

克劳德桌面版

添加到您的Claude Desktop MCP配置中：

{
  "mcpServers": {
    "clockodo": {
      "command": "node",
      "args": ["/absolute/path/to/your/clockodo-ts/build/index.js"],
      "env": {
        "CLOCKODO_EMAIL": "your-email@example.com",
        "CLOCKODO_API_KEY": "your-api-key"
      }
    }
  }
}

或者使用您现有的 .env 文件：

{
  "mcpServers": {
    "clockodo": {
      "command": "node",
      "args": ["/absolute/path/to/your/clockodo-ts/build/index.js"],
      "cwd": "/absolute/path/to/your/clockodo-ts"
    }
  }
}

备注：替换 /absolute/path/to/your/clockodo-ts 使用项目目录的实际绝对路径。

MCP检查员

对于开发和测试：

npx @modelcontextprotocol/inspector

配置为：

  • 服务器命令: npx tsx /absolute/path/to/your/clockodo-ts/src/index.ts
  • 运输标准： stdio
  • 工作目录: /absolute/path/to/your/clockodo-ts

可用资源

用户资源

  • 统一资源标识符: clockodo://users
  • 描述：从Clockodo实例中检索所有注册用户
  • 数据：完整的用户信息，包括姓名、电子邮件、角色和设置
  • 格式：用户对象的JSON数组

Claude中的示例用法：

Can you show me all users from my Clockodo instance?

条目资源

  • 统一资源标识符: clockodo://entries/{userId}/{timeSince}/{timeUntil}
  • 描述：检索给定时间范围内特定用户的时间条目
  • 参数:
    • userId：Clockodo用户ID（编号）
    • timeSince：ISO 8601格式的开始日期（例如。， 2025-09-01T00:00:00Z)
    • timeUntil：ISO 8601格式的结束日期（例如。， 2025-09-30T23:59:59Z)
  • 数据：完整的时间输入信息，包括项目详细信息、花费的时间和描述
  • 格式：入口对象的JSON数组

Claude中的示例用法：

Show me time entries for user 148226 from September 1-30, 2025
What did I work on last week? --clockodo

URI示例:

  • clockodo://entries/148226/2025-09-01T00:00:00Z/2025-09-30T23:59:59Z
  • clockodo://entries/123/2024-12-01T00:00:00Z/2024-12-31T23:59:59Z

项目资源

  • 统一资源标识符: clockodo://projects
  • 描述：从Clockodo实例中检索所有项目
  • 数据：完整的项目信息，包括：
    • 项目名称、编号和描述
    • 客户分配和关系
    • 预算信息（货币金额、硬/软预算）
    • 项目状态（活动、完成、日期）
    • 计费设置和收入因素
    • 详细说明和联系信息
  • 格式：项目对象的JSON数组

Claude中的示例用法：

Show me all projects from Clockodo
Which projects are currently active?
What's the budget for project "Agile Coaching 2025"?

API结构

项目结构

src/
├── index.ts          # Main MCP server entry point
├── clockodo.ts       # Clockodo API client
build/
├── index.js          # Compiled executable
├── clockodo.js       # Compiled API client

关键组件

  • McpServer：处理MCP协议的主服务器实例
  • ClockodoAPI：用于Clockodo与全面日志记录集成的API客户端
  • 标准服务器传输：MCP客户端的通信层
  • Zod模式：API响应的类型验证（用户、条目、项目）
  • 日志记录器：内置日志系统，可写入 clockodo-api.log

发展

脚本

  • npm run dev -使用实时重新加载启动开发服务器
  • npm run build -将TypeScript构建为JavaScript
  • npm test -运行测试（如果已实施）

测试API集成

直接测试Clockodo API连接：

curl "https://my.clockodo.com/api/v3/users?page=1" \
  -H "Accept: application/json" \
  -H "X-ClockodoApiUser: your-email@example.com" \
  -H "X-ClockodoApiKey: your-api-key" \
  -H "X-Clockodo-External-Application: mcp-ts"

MCP协议测试

测试MCP协议响应：

# List all available resources
echo '{"jsonrpc": "2.0", "method": "resources/list", "id": 1, "params": {}}' | npm run dev

# Test users resource
echo '{"jsonrpc": "2.0", "method": "resources/read", "id": 2, "params": {"uri": "clockodo://users"}}' | npm run dev

# Test projects resource
echo '{"jsonrpc": "2.0", "method": "resources/read", "id": 3, "params": {"uri": "clockodo://projects"}}' | npm run dev

# Test entries resource (replace with actual user ID and dates)
echo '{"jsonrpc": "2.0", "method": "resources/read", "id": 4, "params": {"uri": "clockodo://entries/148226/2025-09-01T00:00:00Z/2025-09-30T23:59:59Z"}}' | npm run dev

日志记录和调试

服务器包括全面的日志记录，可以写入 clockodo-api.log:

  • 所有API请求和响应
  • 身份验证详细信息（API密钥被屏蔽）
  • 数据验证结果
  • 错误详细信息和堆栈跟踪

要实时监视日志，请执行以下操作：

tail -f clockodo-api.log

错误处理

服务器包括全面的错误处理：

  • 身份验证错误：Clockodo凭据无效
  • API错误：Clockodo API故障或速率限制
  • 验证错误：API响应格式无效
  • 网络错误：连接超时或网络问题

所有错误都正确格式化为MCP协议错误响应。

安全

  • API凭据需要环境变量
  • 错误消息中没有记录或公开凭据
  • API请求包含正确的身份验证头
  • 所有API响应在处理前都经过验证

贡献

  1. 复刻仓库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

故障排除

常见问题

“需要环境变量”错误：

  • 确保 .env 文件存在正确的凭据
  • 检查一下 dotenv.config() 在导入其他模块之前调用

“无效的API响应格式”错误：

  • 验证您的Clockodo API凭据是否正确
  • 检查您的API密钥是否具有正确的权限
  • 确保您的Clockodo帐户可以访问用户端点

MCP连接问题：

  • 验证服务器在开发模式下启动时没有错误
  • 检查您的MCP客户端配置是否指向正确的路径
  • 确保服务器进程具有适当的权限

调试模式

使用调试输出运行：

DEBUG=* npm run dev

许可证

[在此处添加您的许可证]

支持

关于以下问题：

相关 MCP