productive-mcp

一个用于 Productive.io 的 MCP 服务器 — 使用简单的英语从任何兼容 MCP 的客户端（Claude Code、Claude Desktop、Cursor 等）记录时间、检查项目和管理时间条目：

"log 2.5 hours on the Acme security review project"

"show me my time entries for last week"

"delete time entry 123456"

基于 Productive.io JSON:API v2 构建，具有模糊项目匹配、本地磁盘缓存以及每个项目的默认服务记忆功能，因此常见情况（为您经常使用的项目记录时间）只需一句话即可完成。

功能

• 9 个工具，涵盖项目、服务和时间条目（列表/创建/更新/删除）

• 模糊项目匹配 — "Acme"、"1099 Acme" 或 "1099" 都会解析为同一个项目

• 记住每个项目的默认服务，因此您不必每次都指定它

• 本地缓存，用于项目和服务（1 小时 TTL，可手动刷新）

• 凭据安全：默认从 macOS 钥匙串读取 API 令牌（支持环境变量作为 Linux/WSL 或无头环境的后备方案）

• 输入 hours，输出 hours — API 内部使用分钟，但您永远不会看到它们

• 默认范围限定为“我” — list_time_entries 仅显示您自己的条目，除非您选择退出

要求

• Python 3.11+

• 拥有已启用 API 访问权限的 Productive.io 账户

• macOS（推荐，用于钥匙串集成）— Linux / WSL 可通过环境变量工作

安装

1. 克隆并安装

git clone https://github.com/<you>/productive-mcp.git
cd productive-mcp
uv venv
uv pip install -e .

（如果您不使用 uv，则使用 python -m venv .venv && .venv/bin/pip install -e .）

2. 获取您的 Productive 凭据

您需要三个值：

3. 存储凭据

选项 A — macOS 钥匙串（macOS 上推荐）

security add-generic-password -s productive-mcp -a token      -w "<token>"      -U
security add-generic-password -s productive-mcp -a org_id     -w "<org_id>"     -U
security add-generic-password -s productive-mcp -a person_id  -w "<person_id>"  -U

服务器在启动时通过 security CLI 查找这些凭据。本项目绝不会将它们写入磁盘。

选项 B — 环境变量（Linux / WSL / CI / 覆盖）

export PRODUCTIVE_MCP_TOKEN="<token>"
export PRODUCTIVE_MCP_ORG_ID="<org_id>"
export PRODUCTIVE_MCP_PERSON_ID="<person_id>"

环境变量优先于钥匙串查找，因此它们也是临时测试其他账户的最简单方法。

4. 向您的 MCP 客户端注册服务器

Claude Code (~/.claude.json)

在 mcpServers 下添加：

{
  "mcpServers": {
    "productive": {
      "type": "stdio",
      "command": "/path/to/productive-mcp/.venv/bin/productive-mcp",
      "args": []
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "productive": {
      "command": "/path/to/productive-mcp/.venv/bin/productive-mcp"
    }
  }
}

编辑配置后重启客户端。

5. (可选) 使用捆绑的部署脚本进行全局安装

如果您想要一个不绑定到克隆目录的共享安装：

bash scripts/install.sh

这将创建一个包含全新 venv 和 run.sh 启动器的 ~/.local/share/productive-mcp/。将您的 MCP 客户端指向 ~/.local/share/productive-mcp/run.sh 而不是 venv 二进制文件。重新运行脚本会就地升级 venv。

工具

所有工具都以 productive_ 为前缀，以便与其他 MCP 服务器整洁地命名空间隔离。

工具参考

productive_log_time

project       : str   — Project name (fuzzy) or numeric id. e.g. "1099 Acme", "42"
hours         : float — Hours worked (e.g. 2.5). Converted to minutes internally.
note          : str?  — Description of the work
date          : str?  — ISO date (YYYY-MM-DD). Defaults to today.
service_hint  : str?  — Service name or id (only needed when the project has
                        multiple services and no remembered default)

成功后，返回创建的条目以及一个 service_resolution 备注，解释服务是如何选择的（"auto-selected only service" / "used remembered default" / "matched by name" 等）。

如果项目只有一个服务，它会被自动选择并保存为下次的默认服务。如果有多个，服务器会返回一个列出选项的可操作错误。

productive_find_project

query : str — Partial name or number (e.g. "Acme", "1099 acme", "1099")
limit : int — Max matches (default 5)

返回按最佳匹配排序的匹配项。模糊评分器结合了标记子字符串匹配、用于拼写错误的序列匹配器后备，以及当查询包含确切项目编号时的提升。

productive_list_time_entries

after     : str?  — Include entries on/after this ISO date
before    : str?  — Include entries on/before this ISO date
project   : str?  — Filter by project name or id
mine_only : bool  — Default True; set False to see the whole team's entries

条目按最新优先返回，总计汇总在 total_hours 中。

工作原理

架构

┌─────────────────────┐   stdio    ┌──────────────────────┐   HTTPS   ┌─────────────────┐
│  MCP client         │ ─────────► │  productive-mcp      │ ────────► │  Productive.io  │
│  (Claude Code etc.) │            │  (FastMCP server)    │           │  JSON:API v2    │
└─────────────────────┘            └──────────┬───────────┘           └─────────────────┘
                                              │
                                              ▼
                                    ~/.config/productive-mcp/
                                    ├── cache.json        (projects, services; 1h TTL)
                                    └── preferences.json  (per-project default service)

关键设计决策

• 服务范围限定为属于项目的交易 (Deals)。 Productive 的数据模型使这一点可见；MCP 透明地遍历层次结构，因此 "services on project X" 可以直接工作。

• 小时是唯一面向用户的单位。 API 以分钟为单位存储时间；此层在边界处进行转换。

• 记忆的默认值减少了往返次数。 在您为项目记录一次时间后，后续调用可以省略 service_hint — 默认值在 preferences.json 中按项目记忆。

• 模糊匹配优于精确匹配。 大多数时间记录请求说的是类似 "that security review for Acme"，而不是 "project #1099"。解析器偏向于自然语言。

• 默认仅限“我”。 您几乎总是为自己记录时间；唯一需要团队范围可见性的人可以传递 mine_only=False。

本地状态

两个文件位于 ~/.config/productive-mcp/ 下，均以 0600 权限创建：

• cache.json — 修剪后的项目列表和每个项目的服务查找。在 TTL 过期时或通过 productive_refresh_cache 自动刷新。

• preferences.json — { "default_services": { "<project_id>": "<service_id>" } }。

这两个文件都不包含任何凭据。

凭据查找顺序

1. 环境变量 (PRODUCTIVE_MCP_TOKEN / _ORG_ID / _PERSON_ID)

2. macOS 钥匙串 (security find-generic-password -s productive-mcp -a <account>)

3. 错误 — 服务器拒绝启动并显示指向这两个选项的有用消息。

开发

uv pip install -e ".[dev]"

# unit tests (no network required)
pytest

# integration tests (hit the real Productive API — requires credentials)
pytest -m integration

# lint + type check
ruff check .
mypy src

直接运行服务器进行调试：

.venv/bin/productive-mcp
# or
python -m productive_mcp

它使用 stdio JSON-RPC 进行通信，因此要手动测试它，您需要一个 MCP 客户端或 mcp-inspector。

项目布局

src/productive_mcp/
├── __main__.py      Entrypoint (`python -m productive_mcp`)
├── server.py        FastMCP tool definitions
├── client.py        Async Productive.io API client + fuzzy matcher
├── auth.py          Keychain / env-var credential loader
└── storage.py       Local cache + preferences persistence
scripts/
└── install.sh       One-shot deploy script for the global launcher
tests/
└── test_client.py   Unit tests for trimming + fuzzy matching

故障排除

"Keychain lookup failed" 该项目尚不存在（重新运行步骤 3 中的 security add-generic-password 命令）或者您不在 macOS 上。请改用环境变量。

"No project matches 'X'" 如果项目是最近创建的，您的缓存可能已过期。调用 productive_refresh_cache 然后重试。

"Ambiguous project query" 两个项目的得分几乎相同。请更具体一点 — 添加项目编号或公司名称。

"Project has multiple services; pass service_hint" 该项目尚未设置默认值。在此次调用中传递 service_hint="…"（它会被记住），或者预先调用 productive_set_default_service 一次。

服务器启动，但客户端报告 "no tools" 确保您的 MCP 客户端指向 venv 的 productive-mcp 二进制文件（或 run.sh 启动器），而不是源文件。FastMCP 在握手时通告工具 — 如果进程无法导入 mcp，则不会出现任何工具。

安全说明

• API 令牌绝不会被本项目写入磁盘。它们仅存在于钥匙串或环境变量中。

• 缓存和首选项文件以 0600 权限创建，且不包含任何凭据。

• Productive API 令牌授予与您的用户相同的访问权限。请相应地对待它。如果您怀疑泄露，请通过 Productive → Settings → API integrations 进行轮换。

替代方案

存在其他几个 Productive.io MCP 服务器 — 在采用此服务器之前值得查看：

• berwickgeek/productive-mcp — 功能最全的通用服务器（项目、任务、看板、人员、工作流）。Node.js。无时间跟踪。

• adamchrabaszcz/productive-time-mcp — 上述服务器的配套时间跟踪服务器。

• druellan/Productive-Simple-MCP — 使用 TOON 输出的只读 Python/FastMCP 服务器，用于低令牌使用。

• laurkee/productive-mcp (Codeberg) — 专注于票务。

为什么要选择这个？ 此服务器专注于 "记录时间并管理条目" 工作流，其 UX 基于三个主观选择：

1. 默认凭据在 macOS 钥匙串中，而不是 .env — 不存在令牌出现在 git status 中的风险。

2. 带有项目编号提升的模糊项目匹配 — 说 "1099 Acme" 或仅 "Acme"；两者都有效。

3. 每个项目的默认服务记忆 — 在项目上进行第一次 productive_log_time 后，后续调用无需指定服务。

如果您主要需要任务/看板/工作流而不是时间记录，请改用 berwickgeek/productive-mcp — 或者并排运行两者（它们使用不同的工具前缀）。

许可证

MIT — 参见 LICENSE。

贡献

欢迎提交问题和 PR。这是一个小项目；请保持更改集中，并为 client.py 中的任何新行为包含测试。

与 Productive.io 无关联。"Productive" 是其各自所有者的商标。