Basecamp MCP Integration

Basecamp MCP Server

Basecamp 3 向けの MCP サーバーです。Codex、Cursor、Claude Desktop などの MCP 対応クライアントから、OAuth 認証による Basecamp API 呼び出しを通じて Basecamp プロジェクトを読み取り、管理できます。

メインサーバーは basecamp_fastmcp.py です。公式の mcp.server.fastmcp Python SDK を使用し、プロジェクト、ToDo、メッセージボード、キャンプファイヤー、カードテーブル、受信トレイへの転送、ドキュメント、アップロード、コメント、イベント、ウェブフック、検索をカバーする 79 個のツールを公開します。

できること

• Basecamp プロジェクトとプロジェクトの詳細を閲覧します。
• プロジェクト、ToDo、メッセージ、キャンプファイヤーの投稿、コメント、アップロード、スケジュールを横断して検索します。
• ToDo リスト、ToDo、ToDo グループ、完了状態を読み取り、管理します。
• 下書きやカテゴリーを含むメッセージボードのメッセージを読み取り、作成します。
• キャンプファイヤーの投稿を読み取ります。
• コメントを読み取り、作成します。
• カードテーブル、列、カード、カードのステップを操作します。
• 受信トレイへの転送と返信を読み取ります。
• 日次チェックインと回答を読み取ります。
• 添付ファイルをアップロードし、アップロード内容を確認します。
• 下書きを含むドキュメントを読み取り、管理します。
• イベントを一覧表示し、ウェブフックを管理します。
• Codex、Cursor、Claude Desktop 用のローカル MCP 設定を生成します。

必要条件

• Python 3.10 以降。
• Basecamp 3 アカウント。
• https://launchpad.37signals.com/integrations から取得した Basecamp OAuth アプリケーション。
• Codex、Cursor、Claude Desktop など、ローカル MCP サーバーを実行できるクライアント。

システムの Python が古い場合は、uv を使用してください。新しい Python バージョンで仮想環境を作成できます。

クイックスタート

リポジトリをクローンして、依存関係をインストールします。

git clone https://github.com/georgeantonopoulos/Basecamp-MCP-Server.git
cd Basecamp-MCP-Server

uv venv --python 3.12 venv
source venv/bin/activate
uv pip install -r requirements.txt

または、python がすでに Python 3.10 以降を指している場合：

python setup.py

サンプルから .env ファイルを作成し、Basecamp OAuth の詳細を入力します。

cp .env.example .env

必須の値：

BASECAMP_CLIENT_ID=your-client-id
BASECAMP_CLIENT_SECRET=your-client-secret
BASECAMP_ACCOUNT_ID=your-account-id
USER_AGENT="Your App Name ([email protected])"

Basecamp で認証します。

python oauth_app.py

http://localhost:8000 を開き、OAuth フローを完了してください。デフォルトでは、トークンはローカルの oauth_tokens.json に保存されます。

MCP クライアントの設定

Codex

python generate_codex_config.py
codex mcp get basecamp

便利なオプション：

python generate_codex_config.py --dry-run
python generate_codex_config.py --legacy

このスクリプトは ~/.codex/config.toml に basecamp サーバーエントリーを書き込み、このチェックアウトの仮想環境と basecamp_fastmcp.py を指定します。

Cursor

python generate_cursor_config.py

その後、Cursor を再起動し、Settings -> MCP を確認してください。サーバーが basecamp として表示されます。

Claude Desktop

python generate_claude_desktop_config.py

その後、Claude Desktop を完全に終了してから、再度開いてください。生成された設定は次の場所に書き込まれます。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：~/AppData/Roaming/Claude/claude_desktop_config.json
• Linux：~/.config/claude-desktop/claude_desktop_config.json

サーバーの確認

stdio 経由で FastMCP サーバーを実行し、ツール一覧を確認します。

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | python basecamp_fastmcp.py

自動テストを実行します。

python -m pytest tests/ -v

利用可能なツール

FastMCP サーバーは 82 個のツールを公開します。

プロジェクトと検索

• get_projects
• get_project
• search_basecamp
• global_search

レポート

• get_assignable_people — ToDo を割り当て可能なすべてのユーザー （GET /reports/todos/assigned.json）
• get_person_assignments — すべてのプロジェクトを横断して、1 人のユーザーに割り当てられたすべてのアクティブな未完了 ToDo（GET /reports/todos/assigned/{id}.json、 任意の group_by: bucket|date）。1 人のユーザーに割り当てられたすべての ToDo が必要な場合は、プロジェクトを順に調べるよりこちらを優先してください。
• get_overdue_todos — すべてのプロジェクトにおける期限超過 ToDo を、期限超過期間別にグループ化して表示します （GET /reports/todos/overdue.json）

ToDo

• get_todolists
• get_todolist
• create_todolist
• update_todolist
• trash_todolist
• get_todos
• get_todo
• create_todo
• update_todo
• delete_todo
• archive_todo
• complete_todo
• uncomplete_todo
• reposition_todo
• get_todolist_groups
• create_todolist_group
• reposition_todolist_group

メッセージ、キャンプファイヤー、チェックイン

• get_message_board
• get_messages
• get_message
• get_message_categories
• create_message
• create_draft_message

create_message に publish: false を渡すと、すぐに投稿する代わりに下書きメッセージを作成できます。意図する操作が下書きの作成である場合は、エージェントが create_draft_message を直接呼び出すこともできます。

• get_campfire_lines
• get_daily_check_ins
• get_question_answers

コメント

• get_comments
• create_comment

カードテーブル

• get_card_tables
• get_card_table
• get_columns
• get_column
• create_column
• update_column
• move_column
• update_column_color
• put_column_on_hold
• remove_column_hold
• watch_column
• unwatch_column
• get_cards
• get_card
• create_card
• update_card
• move_card
• complete_card
• uncomplete_card
• get_card_steps
• create_card_step
• get_card_step
• update_card_step
• delete_card_step
• complete_card_step
• uncomplete_card_step

受信トレイの転送

• get_inbox
• get_forwards
• get_forward
• get_inbox_replies
• get_inbox_reply
• trash_forward

ドキュメント、アップロード、添付ファイル、イベント、Webhook

• create_attachment
• get_uploads
• get_upload
• download_upload — Vault の Upload 記録（Docs & Files）をダウンロードし、そのバイト列を MCP コンテンツとして返します（画像 MIME タイプの場合は ImageContent、それ以外の場合は EmbeddedResource / BlobResourceContents）。MCP ホストが Blob をモデルに転送するため、PDF、画像、ドキュメントを帯域外の取得なしでネイティブに読み取れます。
• download_attachment — インラインのコメント／メッセージ添付ファイルを、その content_attachments[].download_url からダウンロードし、MCP コンテンツとして返します。コメントまたはメッセージ本文に埋め込まれたファイルには、こちらを使用します。インライン添付ファイルは独自の ID を持つ Attachment オブジェクトであり、/uploads/{id} では解決できません。このエンドポイントは 404 を返します。Vault 内の独立した Upload 記録であるファイルには、代わりに download_upload を使用してください。

download_upload と download_attachment のホスト互換性。 どちらのツールも MCP コンテンツブロックを返します。MCP ホストが ImageContent / EmbeddedResource (BlobResourceContents) を転送する場合に限り、モデルはファイルを読み取れます。2026 年 6 月時点の状況：

• Claude Code (CLI) — application/pdf やその他のバイナリ Blob リソースを含め、完全にサポートされています。
• Claude Desktop / claude.ai web — 画像コンテンツブロックは機能しますが、画像以外の EmbeddedResource ブロックは "Resources of type 'application/pdf' are not currently supported" として拒否されます。バイト列はホストに届きますが、モデルには届きません。クライアントがサポートを追加すれば、サーバーに変更を加えることなく、これらのフロントエンドでもツールが役立つようになります。

• get_documents
• get_document
• create_document
• create_draft_document

create_document に publish: false を渡すと、すぐに公開する代わりに下書きドキュメントを作成できます。意図する操作が下書きの作成である場合は、エージェントが create_draft_document を直接呼び出すこともできます。

• update_document
• trash_document
• get_events
• get_webhooks
• create_webhook
• delete_webhook

プロンプトの例

• 「Basecamp のすべてのプロジェクトを表示してください。」
• 「Basecamp で deadline を検索してください。」
• 「プロジェクト 123456 の ToDo リストを取得してください。」
• 「ToDo リスト 987654 に Review PR という名前の ToDo を作成してください。」
• 「プロジェクト 123456 のメッセージボードのカテゴリを表示してください。」
• 「プロジェクトのメッセージボードにお知らせを投稿してください。」
• 「プロジェクト 123456 のカードテーブルの列を表示してください。」
• 「このカードを Done 列に移動してください。」
• 「このプロジェクトの保管庫にアップロードされた最新のファイルを一覧表示してください。」
• 「コメントに添付されたスクリーンショットをダウンロードして、内容を読めるようにしてください。」

アーキテクチャ

• basecamp_fastmcp.py：MCP クライアントが使用する FastMCP stdio サーバーです。
• basecamp_client.py：同期型の Basecamp 3 API クライアントです。
• search_utils.py：Basecamp のリソースを横断して検索する高レベルのヘルパーです。
• oauth_app.py：Basecamp 認証用のローカル Flask OAuth フローです。
• auth_manager.py：API 呼び出しの前に使用する OAuth トークン更新ヘルパーです。
• token_storage.py：ローカルの OAuth トークンストレージです。
• generate_codex_config.py：Codex MCP 設定ジェネレーターです。
• generate_cursor_config.py：Cursor MCP 設定ジェネレーターです。
• generate_claude_desktop_config.py：Claude Desktop 設定ジェネレーターです。
• mcp_server_cli.py：互換性とテストのために残されているレガシー JSON-RPC サーバーです。

認証とトークンの保存

推奨される方法は OAuth 2.0 です。

1. Basecamp OAuth アプリを作成します。
2. クライアント ID、クライアントシークレット、アカウント ID、リダイレクト URI、ユーザーエージェントを .env に設定します。
3. python oauth_app.py を実行します。
4. http://localhost:8000 でブラウザーのフローを完了します。

デフォルトでは、OAuth トークンは <project>/oauth_tokens.json に保存されます。コンテナー、読み取り専用のチェックアウト、またはマウントされたトークンボリュームを使用する場合は、BASECAMP_MCP_TOKEN_FILE を設定します。

export BASECAMP_MCP_TOKEN_FILE=/var/lib/basecamp-mcp/oauth_tokens.json

OAuth アプリと MCP サーバーは、どちらも同じ変数を読み取ります。token_storage.py はこのパス内の ~ と環境変数を展開し、必要に応じて親ディレクトリを作成します。また、書き込み時にトークンファイルの権限を 0o600 に設定しようとします。親ディレクトリの権限は、引き続きご自身で管理してください。

組み込みの OAuth ウェブサーバーは、コールバックの認証コードが記録されないよう、アクセスログからクエリ文字列を除外します。別のウェブサーバーやリバースプロキシの背後で実行する場合は、そのサーバーのアクセスログでもクエリ文字列を除外するよう設定してください。

トラブルシューティング

MCP クライアントにツールが表示されない場合：

1. 仮想環境が存在し、MCP SDK がインストールされていることを確認します。

   ./venv/bin/python -c "import mcp; print('MCP available')"
   

2. .env に BASECAMP_ACCOUNT_ID が含まれていることを確認します。

3. 該当する設定ジェネレーターを再実行します。

4. MCP クライアントを完全に終了してから、再起動します。

認証に失敗した場合：

python oauth_app.py

次に、http://localhost:8000 を開き、Basecamp OAuth フローをもう一度完了してください。

macOS の Claude Desktop では、MCP のログは通常、次の場所にあります。

~/Library/Logs/Claude/

セキュリティに関する注意事項

• .env や oauth_tokens.json をコミットしないでください。
• Basecamp は API クライアントに識別情報を示すよう求めているため、連絡先情報を含む、内容が分かりやすい USER_AGENT を使用してください。
• トークンファイルは、ローカルストレージまたは適切な権限が設定されたストレージに保管してください。
• このサーバーは、ローカルの MCP クライアントでの使用を想定しています。ネットワーク上に公開する前に、コードとデプロイモデルを確認してください。

ライセンス

MIT。詳細は LICENSE を参照してください。

Star の推移