keeping-mcp

keeping-mcp

开源的 Model Context Protocol（MCP）服务，将 Keeping（api.keeping.nl）时间追踪 API 作为工具开放，供 AI 编码助手调用。专为使用 Claude Code（或任何支持 MCP 的客户端）的独立开发者打造，让他们在会话结束时将可计费工时记录到 Keeping，而不必手动输入，同时保留 Keeping 现有的原生 Jortt 开票集成。默认情况下，每个写入工具都会进行 dry-run——只有你明确确认后，工时才会发送到 Keeping。

⚠ 写入操作默认采用 dry-run

每个写入工具（keeping_add_entry、keeping_update_entry、keeping_delete_entry、 keeping_start_timer、keeping_stop_timer、keeping_resume_timer）都会返回 预览，除非你在工具调用中传入 confirm: true。

在环境中设置 KEEPING_REQUIRE_CONFIRM=false 会禁用此保护机制。 届时，首次调用就会执行写入——不会有第二次确认机会。

建议：除非你在非交互式自动化环境中运行 服务，并且明确接受失去确认步骤的后果，否则切勿禁用此保护机制。

安装

从 npm 安装

无需安装——npx 会在首次运行时获取软件包：

KEEPING_TOKEN=kp_live_your_token_here npx -y keeping-mcp

此服务使用 MCP stdio 协议，并在前台运行，等待从 stdin 接收 JSON-RPC 帧——按 Ctrl+C 退出。实际使用时，你无需手动运行它；支持 MCP 的客户端（Claude Code、Claude Desktop、Cursor 等）会使用下面的配置片段为你启动它。

可选——全局安装，让 keeping-mcp 出现在你的 PATH 中：

npm install -g keeping-mcp
KEEPING_TOKEN=kp_live_your_token_here keeping-mcp

需要 Node.js >=22。此软件包发布于 npmjs.com/package/keeping-mcp，并附带 sigstore 来源证明。

Windows 11 上的 Claude Code

将配置添加到 %APPDATA%\Claude\claude_desktop_config.json，或添加到项目的 .mcp.json 文件中。

{
  "mcpServers": {
    "keeping-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "keeping-mcp"],
      "env": {
        "KEEPING_TOKEN": "kp_live_your_token_here"
      }
    }
  }
}

在 Windows 上必须使用 cmd /c 包装器——npx 会解析为 npx.cmd，而 Claude Code 的进程启动不会搜索 PATHEXT 扩展名（参见 anthropics/claude-code#58510）。

macOS / Linux 上的 Claude Code

将配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 ~/.config/Claude/claude_desktop_config.json（Linux），也可以添加到项目的 .mcp.json 中。

{
  "mcpServers": {
    "keeping-mcp": {
      "command": "npx",
      "args": ["-y", "keeping-mcp"],
      "env": {
        "KEEPING_TOKEN": "kp_live_your_token_here"
      }
    }
  }
}

其他 MCP 客户端

任何支持 stdio 传输的 MCP 客户端均可使用。此服务由 npx -y keeping-mcp 启动，并从其环境中读取 KEEPING_TOKEN。可在 MCP Registry 中通过 io.github.Red-Square-Software/keeping-mcp 找到。

获取 Keeping 访问令牌

1. 登录你的 Keeping 账户。
2. 打开偏好设置（右上角菜单）。
3. 找到显示开发者功能部分并启用它。
4. 系统会显示新的个人访问令牌部分。
5. 点击生成新令牌，为其命名（例如“Claude Code”），然后复制令牌值。
6. 将其存储为 shell 环境中的 KEEPING_TOKEN，或存储在 Claude Code 配置的 env 代码块中。

此令牌对你的时间条目拥有完整的读写权限——请像对待密码一样保管它。切勿将其提交到 git，切勿粘贴到聊天中，也切勿从工具响应中读取它（keeping-mcp 从不回显该令牌）。

配置

变量	必需	默认值	用途
KEEPING_TOKEN	是	—	Keeping 个人访问令牌（通过上文所述部分创建）。
KEEPING_REQUIRE_CONFIRM	否	true	为 true 时，写入工具会返回预览，除非调用时传入 confirm: true。设为 false 会完全关闭此保护机制——请参阅下方警告。
KEEPING_ORG_ID	否	—	将所有调用固定到一个组织 ID。未设置且令牌可访问多个组织时，每次调用写入工具都必须显式提供 organisation_id 输入。
KEEPING_LOG_LEVEL	否	info	服务 stderr 日志详细程度。可选值：debug、info、warn、error。

⚠ 写入默认采用试运行模式

每个写入工具（keeping_add_entry、keeping_update_entry、keeping_delete_entry、 keeping_start_timer、keeping_stop_timer、keeping_resume_timer）都会返回 预览，除非你在工具调用中传入 confirm: true。

在环境中设置 KEEPING_REQUIRE_CONFIRM=false 会关闭此保护机制。 随后，首次调用便会执行写入——没有第二次确认机会。

建议：切勿关闭此保护机制，除非你在非交互式自动化环境中运行 此服务，并已明确接受失去确认步骤的风险。

工具

keeping-mcp 在服务启动时会注册 12 个工具。读取工具（keeping_me、keeping_organisations、keeping_projects、keeping_tasks、keeping_list_entries、keeping_timer_status）调用 Keeping 的 API 时无需确认。写入工具（keeping_add_entry、keeping_update_entry、keeping_delete_entry、keeping_start_timer、keeping_stop_timer、keeping_resume_timer）会返回试运行预览，除非调用时传入 confirm: true（默认行为由 KEEPING_REQUIRE_CONFIRM 控制）。

试运行工作流（对话示例）

写入工具遵循两步模式：先提议，再确认。首次调用会返回服务将发送的 HTTP 请求预览；第二次调用（传入 confirm: true）才会实际发送请求。

步骤 1——预览（未传入 confirm，不会调用 API）。仅作说明；实际字段名称与 Keeping 的 OpenAPI 一致（参见 https://developer.keeping.nl）。

{
  "tool": "keeping_add_entry",
  "input": {
    "description": "Phase 4 release prep",
    "hours": 1.5,
    "project_id": 123
  },
  "response": {
    "would_post": {
      "method": "POST",
      "url": "https://api.keeping.nl/v1/456/time-entries",
      "body": {
        "description": "Phase 4 release prep",
        "hours": 1.5,
        "project_id": 123,
        "date": "2026-06-12",
        "purpose": "work"
      }
    }
  }
}

步骤 2——确认（添加 confirm: true，请求将发送到 Keeping）。仅作说明；实际响应结构与 Keeping 的 OpenAPI 一致。

{
  "tool": "keeping_add_entry",
  "input": {
    "description": "Phase 4 release prep",
    "hours": 1.5,
    "project_id": 123,
    "confirm": true
  },
  "response": {
    "id": 98765,
    "day": "2026-06-12",
    "hours": 1.5,
    "description": "Phase 4 release prep",
    "project_id": 123,
    "purpose": "work"
  }
}

验证来源

版本通过 GitHub Actions OIDC 可信发布方式发布（无需长期有效的 npm 令牌）。每个版本都附带 npm 来源证明，将已发布的 tarball 与此仓库中的特定提交关联起来。

npm audit signatures
# or, for a single package:
npm view keeping-mcp --json | jq '.dist.attestations'

本地开发

git clone https://github.com/red-square-software/keeping-mcp.git
cd keeping-mcp
npm ci
npm test
npm run build
KEEPING_TOKEN=kp_live_your_token_here node dist/bin/keeping-mcp.js

所有服务输出都写入 stderr——stdout 专用于 MCP JSON-RPC 消息帧。切勿将诊断输出写入 stdout；请使用 console.error 记录日志。

许可证

MIT——参见 LICENSE。