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 構建。