@nicola5tor/openproject-timelog

MCP 服务器（Model Context Protocol），用于记录本地工时日志并与 OpenProject（API v3）同步。从 Claude Desktop（或其他 MCP 客户端）以自然语言记录你的工作，随时查看，并在准备好后上传到 OpenProject。

• 传输： stdio

• 本地存储： ~/.openproject-timelog/entries.json

• 配置： 环境变量 OPENPROJECT_URL 和 OPENPROJECT_API_KEY

安装

无需全局安装任何东西：服务器通过 npx 运行。

# probarlo directamente
npx @nicola5tor/openproject-timelog

或者安装到项目中：

npm install @nicola5tor/openproject-timelog
# o
pnpm add @nicola5tor/openproject-timelog

Related MCP server: OpenProject MCP Server

在 Claude Desktop 中配置

编辑配置文件（claude_desktop_config.json），在 mcpServers 下添加服务器：

{
  "mcpServers": {
    "openproject-timelog": {
      "command": "npx",
      "args": ["-y", "@nicola5tor/openproject-timelog"],
      "env": {
        "OPENPROJECT_URL": "https://tu-openproject.example.com",
        "OPENPROJECT_API_KEY": "TU_API_KEY"
      }
    }
  }
}

保存后重启 Claude Desktop。

如何获取你的 OpenProject API 密钥

在 OpenProject 中：我的账户 → Access tokens → API，然后生成一个密钥。服务器使用 Basic auth 进行身份验证，用户名为字面量 apikey，你的密钥作为密码。

仅本地的工具（log_entry、list_entries、edit_entry、assign_entry、delete_entry、clear_sent）即使不配置 OpenProject 也能正常工作。查询和上传工具需要 OPENPROJECT_URL 和 OPENPROJECT_API_KEY。

工具

本地日志

查询 OpenProject

同步

\* = requerido.

行为说明

• 本地 id 是 UUID v4。工时以十进制保存（1.5 = 1h30m），上传时转换为 ISO 8601 时长（PT1H30M）。

• 如果条目未指定 projectId，上传时会从 work package 派生（额外调用一次 OpenProject）。

• JSON 文件以原子方式写入（临时文件 + rename），操作会被串行化以避免损坏。

• 网络 / 凭据 / 权限错误会作为可读消息在工具的响应中返回，不会导致服务器崩溃。

对话使用示例

你： 记录今天修复登录的 2 小时，任务 1234。 Claude： （调用 log_entry，description="修复登录"、hours=2、workPackageId=1234）

你： 给我记 45 分钟会议，任务我稍后再设置。 Claude： （log_entry description="会议"、hours=0.75） —— 保持待分配。

你： 我有什么待上传的？ Claude： （list_entries status="pending"）

你： 给那两条会议记录设置任务 1234。 Claude： （assign_entry entryIds=[...]、workPackageId=1234）

你： 有哪些活动？把所有条目都设为 "Development" 并上传。 Claude： （get_activities → edit_entry/assign 设置 activityId → upload_entries）

你： 清理已上传的条目。 Claude： （clear_sent）

开发

npm install      # instala deps y compila (prepare -> build)
npm run build    # compila TypeScript a dist/
npm start        # ejecuta dist/index.js

结构：

openproject-timelog/
├── src/
│   ├── index.ts        # entry point, setup MCP y registro de tools
│   ├── store.ts        # CRUD bitácora local (JSON atómico)
│   ├── openproject.ts  # cliente API OpenProject v3
│   └── types.ts        # interfaces/types
├── package.json
├── tsconfig.json
└── README.md

许可证

MIT