productive-mcp

Productive.io 用の MCP サーバーです。MCP 対応クライアント（Claude Code、Claude Desktop、Cursor など）から、自然な英語を使って時間の記録、プロジェクトの確認、タイムエントリーの管理が可能です：

"log 2.5 hours on the Acme security review project" ("Acme セキュリティレビュープロジェクトに 2.5 時間記録して")

"show me my time entries for last week" ("先週のタイムエントリーを見せて")

"delete time entry 123456" ("タイムエントリー 123456 を削除して")

Productive.io JSON:API v2 をベースに構築されており、あいまいなプロジェクトマッチング、ローカルディスクキャッシュ、プロジェクトごとのデフォルトサービス記憶機能を備えているため、頻繁に使用するプロジェクトへの時間記録といった一般的な操作を、たった一文で行うことができます。

機能

• 9 つのツール: プロジェクト、サービス、タイムエントリー（一覧表示 / 作成 / 更新 / 削除）をカバー

• あいまいなプロジェクトマッチング: "Acme"、"1099 Acme"、"1099" はすべて同じプロジェクトとして解決されます

• プロジェクトごとのデフォルトサービス記憶: 毎回指定する必要はありません

• ローカルキャッシュ: プロジェクトとサービス用（TTL 1時間、手動更新可能）

• 認証情報の安全性: API トークンはデフォルトで macOS キーチェーンから読み取られます（Linux/WSL やヘッドレス環境向けに環境変数もサポート）

• 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 つの値が必要です：

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 クライアントのパスを venv バイナリではなく ~/.local/share/productive-mcp/run.sh に指定してください。スクリプトを再実行すると、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)

成功すると、作成されたエントリーと、サービスがどのように選択されたか（"auto-selected only service" / "used remembered default" / "matched by name" など）を説明する service_resolution ノートが返されます。

プロジェクトにサービスが 1 つしかない場合、自動的に選択され、次回のためにデフォルトとして保存されます。複数ある場合、サーバーは選択肢をリストしたアクション可能なエラーを返します。

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 にプロジェクトごとに記憶されます。

• 完全一致よりもあいまい一致を優先。 時間記録のリクエストのほとんどは "project #1099" ではなく "that security review for Acme" のような形式です。リゾルバーは自然言語に偏重しています。

• デフォルトで「自分のみ」。 ほとんどの場合、自分自身の時間を記録するためです。チーム全体の可視性が必要な場合は mine_only=False を渡すことができます。

ローカル状態

~/.config/productive-mcp/ の下に 2 つのファイルが作成され、どちらも 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" 2 つのプロジェクトがほぼ同じスコアでした。プロジェクト番号や会社名を追加して、より具体的に指定してください。

"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 → 設定 → API インテグレーションからローテーションしてください。

代替案

他にもいくつかの Productive.io MCP サーバーが存在します。採用前に確認することをお勧めします：

• berwickgeek/productive-mcp — 最も機能が充実した汎用サーバー（プロジェクト、タスク、ボード、人、ワークフロー）。Node.js 製。時間記録機能なし。

• adamchrabaszcz/productive-time-mcp — 上記のコンパニオン時間記録サーバー。

• druellan/Productive-Simple-MCP — トークン消費を抑えるために TOON 出力を使用する読み取り専用の Python/FastMCP サーバー。

• laurkee/productive-mcp (Codeberg) — チケット管理に特化。

なぜこれを選ぶのか？ このサーバーは「時間の記録とエントリーの管理」ワークフローに特化しており、UX は以下の 3 つのこだわりに基づいています：

1. デフォルトで macOS キーチェーンに認証情報を保存 — .env を使用しないため、git status にトークンが紛れ込むリスクがありません。

2. プロジェクト番号ブースト付きのあいまいマッチング — "1099 Acme" でも単に "Acme" でも機能します。

3. プロジェクトごとのデフォルトサービス記憶 — プロジェクトで最初の productive_log_time を行った後は、以降の呼び出しでサービスを指定する必要はありません。

タスク/ボード/ワークフローが主な目的で、時間記録が主でない場合は、berwickgeek/productive-mcp を使用するか、両方を並行して実行してください（ツールプレフィックスが異なるため共存可能です）。

ライセンス

MIT — LICENSE を参照してください。

貢献

Issue や PR を歓迎します。これは小さなプロジェクトですので、変更は焦点を絞り、新しい動作については client.py にテストを含めてください。

Productive.io とは提携していません。「Productive」は各所有者の商標です。