金大哥 - basecamp-mcp MCP 详情

article

README

🚀 Basecamp MCP 服务器

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

🚀 快速开始

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

先决条件

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

设置步骤

1. 注册 Basecamp OAuth 应用

访问 https://launchpad.37signals.com/integrations
点击“Register your application”
填写详细信息：
- 名称：Claude Code MCP（或你喜欢的任何名称）
- 网站：你的网站或 http://localhost
- 重定向 URI：http://localhost:9876/callback
保存并记录你的 客户端 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 服务器将执行以下操作：

打开你的浏览器，跳转到 Basecamp 的授权页面
你授权后，重定向到 localhost:9876/callback
将令牌存储在 ~/.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>"

📚 详细文档

可用工具

项目

| 工具 | 描述 | |------|-------------| | basecamp_list_projects | 列出所有项目（可根据状态过滤） | | basecamp_get_project | 获取项目详细信息，包括停靠工具 | | basecamp_create_project | 创建一个新项目 | | basecamp_update_project | 更新项目名称/描述 | | basecamp_trash_project | 将项目移至回收站 |

待办事项

| 工具 | 描述 | |------|-------------| | basecamp_list_todolists | 列出项目中的待办列表 | | basecamp_get_todolist | 获取待办列表详细信息 | | basecamp_create_todolist | 创建一个新的待办列表 | | basecamp_list_todos | 列出待办列表中的待办事项 | | basecamp_get_todo | 获取待办事项详细信息 | | basecamp_create_todo | 创建一个带有负责人和截止日期的待办事项 | | basecamp_update_todo | 更新一个待办事项 | | basecamp_complete_todo | 将待办事项标记为已完成 | | basecamp_uncomplete_todo | 将待办事项标记为未完成 |

消息

| 工具 | 描述 | |------|-------------| | basecamp_list_messages | 列出公告板上的消息 | | basecamp_get_message | 获取消息详细信息 | | basecamp_create_message | 发布一条新消息 | | basecamp_update_message | 更新一条消息 |

| 工具 | 描述 | |------|-------------| | basecamp_list_comments | 列出任何项目上的评论 | | basecamp_create_comment | 添加一条评论 | | basecamp_update_comment | 更新一条评论 |

人员

| 工具 | 描述 | |------|-------------| | basecamp_list_people | 列出账户中的所有人员 | | basecamp_get_person | 获取人员详细信息 | | basecamp_get_me | 获取当前用户的个人资料 | | basecamp_list_project_people | 列出项目成员 |

日程安排

| 工具 | 描述 | |------|-------------| | basecamp_list_schedule_entries | 列出日历事件 | | basecamp_get_schedule_entry | 获取事件详细信息 | | basecamp_create_schedule_entry | 创建一个日历事件 | | basecamp_update_schedule_entry | 更新一个日历事件 |

文档

| 工具 | 描述 | |------|-------------| | basecamp_list_documents | 列出文档库中的文档 | | basecamp_get_document | 获取文档内容 | | basecamp_create_document | 创建一个新文档 | | basecamp_update_document | 更新一个文档 |

故障排除

"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 构建。

basecamp-mcp