Basecamp MCP Integration

Basecamp MCP 服务

一个适用于 Basecamp 3 的 MCP 服务。它可让支持 MCP 的客户端（例如 Codex、Cursor 和 Claude Desktop）通过经过 OAuth 身份验证的 Basecamp API 调用来读取和管理 Basecamp 项目。

主服务是 basecamp_fastmcp.py。它使用官方的 mcp.server.fastmcp Python SDK，并提供 79 个工具，涵盖项目、待办事项、留言板、Campfire、卡片表格、收件箱转发、文档、上传、评论、事件、Webhooks 和搜索。

功能

• 浏览 Basecamp 项目和项目详情。
• 搜索项目、待办事项、消息、Campfire 发言、评论、上传和日程。
• 读取和管理待办清单、待办事项、待办事项分组及完成状态。
• 读取和创建留言板消息，包括草稿和类别。
• 读取 Campfire 发言。
• 读取和创建评论。
• 使用卡片表格、列、卡片和卡片步骤。
• 读取收件箱转发和回复。
• 读取每日签到及其回答。
• 上传附件并查看上传内容。
• 读取和管理文档，包括草稿。
• 列出事件并管理 Webhooks。
• 为 Codex、Cursor 和 Claude Desktop 生成本地 MCP 配置。

要求

• Python 3.10 或更高版本。
• Basecamp 3 账户。
• 来自 https://launchpad.37signals.com/integrations 的 Basecamp OAuth 应用。
• 可运行本地 MCP 服务的客户端，例如 Codex、Cursor 或 Claude Desktop。

如果系统中的 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

该脚本会将 basecamp 服务条目写入 ~/.codex/config.toml，并将其指向此代码库的虚拟环境和 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 — 所有可被分配待办事项的人员 (GET /reports/todos/assigned.json)
• get_person_assignments — 跨所有项目分配给某一人的所有未完成待办事项 (GET /reports/todos/assigned/{id}.json， 可选参数：group_by: bucket|date)。如果需要查看分配给某一人的所有事项， 优先使用此工具，而不要逐个遍历项目。
• get_overdue_todos — 所有项目中的逾期待办事项，按逾期时长分组 (GET /reports/todos/overdue.json)

待办事项

• 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

消息、Campfire 和签到

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

将 publish: false 传给 create_message，即可创建草稿消息，而不是立即发布。 当预期操作就是创建草稿时，Agent 也可以直接调用 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 主机会将二进制内容转发给模型，因此无需通过带外方式获取，模型即可原生读取 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 网页版 — 支持图像内容块，但 会拒绝非图像 EmbeddedResource 块，并显示 "Resources of type 'application/pdf' are not currently supported"。字节会到达 主机，但不会传给模型。客户端增加支持后，这些工具无需修改服务端 即可在这些前端中使用。

• get_documents
• get_document
• create_document
• create_draft_document

将 publish: false 传给 create_document，即可创建草稿文档，而不是立即发布。 当预期操作就是创建草稿时，Agent 也可以直接调用 create_draft_document。

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

示例提示词

• “显示我所有的 Basecamp 项目。”
• “在 Basecamp 中搜索 deadline。”
• “获取项目 123456 的待办列表。”
• “在待办列表 987654 中创建一个名为 Review PR 的待办事项。”
• “显示项目 123456 的留言板分类。”
• “在项目留言板上发布一条公告。”
• “显示项目 123456 的卡片表格列。”
• “将此卡片移至 Done 列。”
• “列出此项目资料库中的最新上传内容。”
• “下载附在该评论中的屏幕截图，以便你阅读。”

架构

• basecamp_fastmcp.py：供 MCP 客户端使用的 FastMCP 标准输入/输出服务。
• 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 Web 服务会从访问日志中省略查询字符串，以免记录回调授权码。如果你通过其他 Web 服务或反向代理运行它，也请将该服务器的访问日志配置为省略查询字符串。

故障排查

如果 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。
• 使用包含联系信息的描述性 USER_AGENT，因为 Basecamp 要求 API 客户端标识自身。
• 将令牌文件保存在本地或权限设置适当的存储位置。
• 此服务专为本地 MCP 客户端使用而设计。在将其暴露到网络之前，请检查代码和部署模式。

许可证

MIT。请参阅 LICENSE。

Star 历史