Basecamp MCP

🚀 Basecamp MCP 服务器

Basecamp MCP 服务器是一个基于 MCP（模型上下文协议）的服务器，它为 Claude Code 提供了完整的 Basecamp 4 API 访问权限，能帮助用户高效地与 Basecamp 4 平台进行交互。

🚀 快速开始

在使用 Basecamp MCP 服务器之前，请确保你已经满足以下先决条件，并完成相应的设置步骤。

先决条件

• Node.js 18+
• 拥有一个 Basecamp 4 账户
• 从 Basecamp 获取 OAuth 应用凭证

设置步骤

1. 注册 Basecamp OAuth 应用

1. 访问 https://launchpad.37signals.com/integrations
2. 点击“Register your application”
3. 填写详细信息：
   • 名称：Claude Code MCP（或你喜欢的任何名称）
   • 网站：你的网站或 http://localhost
   • 重定向 URI：http://localhost:9876/callback
4. 保存并记录你的 客户端 ID 和 客户端密钥

2. 查找你的账户 ID

你的 Basecamp 账户 ID 位于 Basecamp URL 中：

https://3.basecamp.com/YOUR_ACCOUNT_ID/...

3. 设置环境变量

将以下内容添加到你的 shell 配置文件（如 .bashrc、.zshrc 等）中：

export BASECAMP_CLIENT_ID="your-client-id"
export BASECAMP_CLIENT_SECRET="your-client-secret"
export BASECAMP_ACCOUNT_ID="your-account-id"

4. 构建 MCP 服务器

cd basecamp-mcp
npm install
npm run build

5. 配置 Claude Code

将 MCP 服务器添加到你的 Claude Code 配置中。在项目根目录下创建或编辑 .mcp.json 文件：

{
  "basecamp": {
    "command": "node",
    "args": ["/path/to/basecamp-mcp/dist/index.js"],
    "env": {
      "BASECAMP_CLIENT_ID": "${BASECAMP_CLIENT_ID}",
      "BASECAMP_CLIENT_SECRET": "${BASECAMP_CLIENT_SECRET}",
      "BASECAMP_ACCOUNT_ID": "${BASECAMP_ACCOUNT_ID}"
    }
  }
}

6. 添加权限（可选）

若要自动批准 Basecamp 工具，可在 .claude/settings.json 文件中添加以下内容：

{
  "allow": [
    "mcp__basecamp__*"
  ]
}

首次运行

首次使用时，MCP 服务器将执行以下操作：

1. 打开你的浏览器，跳转到 Basecamp 的授权页面
2. 你授权后，重定向到 localhost:9876/callback
3. 将令牌存储在 ~/.basecamp-mcp/tokens.json 文件中

后续运行将使用存储的令牌（支持自动刷新）。

✨ 主要特性

• 32 种工具覆盖完整的 Basecamp 4 API：
  • 项目管理：支持项目的列出、获取、创建、更新和删除操作
  • 待办事项管理：涵盖待办列表和待办事项的 CRUD 操作以及完成/未完成状态切换
  • 消息管理：可列出、获取、创建和更新消息
  • 评论管理：支持评论的列出、创建和更新
  • 人员管理：可列出人员、获取当前用户信息和项目成员列表
  • 日程安排管理：支持日程条目的列出、获取、创建和更新
  • 文档管理：可列出、获取、创建和更新文档
• OAuth 2.0 认证：支持自动刷新令牌，确保认证过程的便捷性和安全性
• 速率限制处理：具备速率限制处理能力，并提供重试指导，避免因频繁请求而导致的错误

📦 安装指南

请参考上述“快速开始”部分中的“设置步骤”进行安装和配置。

💻 使用示例

基础用法

# 列出所有项目
basecamp_list_projects

# 获取项目详细信息（包含其他工具的停靠 ID）
basecamp_get_project project_id:12345

# 创建一个待办事项
basecamp_create_todo project_id:12345 todolist_id:67890 content:"Review PR #123" due_on:"2024-01-20"

# 发布一条消息
basecamp_create_message project_id:12345 message_board_id:11111 subject:"Sprint Update" content:"<p>All tasks completed!</p>"

📚 详细文档

可用工具

项目

待办事项

消息

评论

人员

日程安排

文档

故障排除

"Missing BASECAMP_CLIENT_ID or BASECAMP_CLIENT_SECRET"

确保你已经设置并导出了相应的环境变量。

"Missing BASECAMP_ACCOUNT_ID"

从 Basecamp URL 中找到你的账户 ID（3.basecamp.com/ 后面的数字）。

OAuth 流程未完成

• 确保端口 9876 可用
• 检查 Basecamp 应用中的重定向 URI 是否与 http://localhost:9876/callback 完全匹配

速率限制（429 错误）

服务器将报告 Retry-After 值，请等待一段时间后再试。

令牌存储

OAuth 令牌存储在 ~/.basecamp-mcp/tokens.json 文件中，权限设置为 600。若要重新认证，请删除该文件并重启 Claude Code。

API 参考

本项目基于 Basecamp 4 API 构建。