AI导哈

Basecamp MCP集成服务器

一个为Basecamp 3设计的TypeScript MCP服务器，通过Model Context Protocol与Claude Desktop和Cursor IDE无缝集成，提供46种API工具以实现完整的Basecamp控制。

  • by jhliberty
  • TypeScript
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 jhliberty/basecamp-mcp-server

使用说明

大本营MCP集成

现代 TypeScript MCP服务器 对于Basecamp 3，通过模型上下文协议提供与Claude Desktop和Cursor IDE的无缝集成。使用官方@modelcontextprotocol/sdk构建，并准备安装NPX。

✅ TypeScript优先： 具有完全异步/等待支持的现代类型安全实现
🚀 NPX就绪： 安装并运行 npx @basecamp/mcp-server
⚡ 46 API工具： 完成Basecamp 3与所有主要功能的集成

快速设置

NPX安装（推荐）

# Install and set up in one command
npx jhliberty/basecamp-mcp-server setup

# Authenticate with Basecamp
npx jhliberty/basecamp-mcp-server auth

# Configure for your AI assistant
npx jhliberty/basecamp-mcp-server config claude   # For Claude Desktop
npx jhliberty/basecamp-mcp-server config cursor  # For Cursor IDE

先决条件

  • Node.js 18+ （ES模块需要）
  • Basecamp 3帐户
  • Basecamp OAuth应用程序（在https://launchpad.37signals.com/integrations)

地方发展设置

为了发展

  1. 克隆并构建项目：

    git clone <repository-url>
cd basecamp-mcp-server
npm install
npm run build

  2. 运行安装脚本：

    npm run setup

    安装脚本会自动执行以下操作：

    • ✅ 安装所有TypeScript依赖项
    • ✅ 将项目构建为 dist/
    • ✅ 创建 .env 模板文件
    • ✅ 测试MCP服务器功能

  3. 配置OAuth凭据： 编辑生成的 .env 文件：

    BASECAMP_CLIENT_ID=your_client_id_here
BASECAMP_CLIENT_SECRET=your_client_secret_here
BASECAMP_ACCOUNT_ID=your_account_id_here
USER_AGENT="Your App Name (your@email.com)"

  4. 通过Basecamp进行身份验证：

    npm run auth

    访问http://localhost:8000并完成OAuth流程。

  5. 生成配置：

    npm run config:cursor  # For Cursor IDE
npm run config:claude  # For Claude Desktop

  6. 完全重新启动您的AI助手 （退出并重新打开）

  7. 在您的AI助手中验证：

    • 光标：转到设置→ MCP，寻找带有绿色复选标记的“大本营”
    • 克劳德桌面：查找工具图标(🔍) 聊天界面
    • 可用工具： 46工具 实现完整的大本营控制

测试您的设置

# Quick test the MCP server
echo '{"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":{}}' | node dist/index.js

# Run automated tests  
npm test

# Run tests with UI
npm run test:ui

适用于Claude桌面用户

基于 MCP官方快速入门指南，Claude Desktop集成遵循以下步骤：

设置步骤

  1. 完成基本设置 （上述开发设置中的步骤1-4）：

    git clone <repository-url>
cd basecamp-mcp-server
npm install
npm run setup
# Configure .env file with OAuth credentials
npm run auth

  2. 生成Claude桌面配置：

    npm run config:claude

  3. 完全重新启动克劳德桌面 （退出并重新打开应用程序）

  4. 在Claude Desktop中验证：

    • 查找“搜索和工具”图标(🔍) 在聊天界面中
    • 你应该看到“大本营”列出了所有46种可用工具
    • 打开工具以启用Basecamp集成

Claude桌面配置

配置在以下位置自动创建：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: ~/AppData/Roaming/Claude/claude_desktop_config.json
  • Linux: ~/.config/claude-desktop/claude_desktop_config.json

生成的配置示例：

{
  "mcpServers": {
    "basecamp": {
      "command": "node",
      "args": ["/path/to/your/project/dist/index.js"],
      "env": {
        "BASECAMP_ACCOUNT_ID": "your_account_id"
      }
    }
  }
}

在Claude Desktop中的使用

问克劳德这样的问题：

  • “我目前的大本营项目是什么？”
  • “向我展示技术项目的最新篝火信息”
  • “在“开发”列中创建标题为“修复登录错误”的新卡”
  • “从营销项目中获取所有待办事项”
  • “搜索包含“截止日期”的邮件”

克劳德桌面故障排除

检查克劳德桌面日志 （以下 官方调试指南):

# macOS/Linux - Monitor logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Check for specific errors
ls ~/Library/Logs/Claude/mcp-server-basecamp.log

常见问题：

  • 工具未出现：验证配置文件语法并重新启动Claude Desktop
  • 连接失败：检查Node.js路径和脚本路径是否为绝对路径
  • 身份验证错误：确保OAuth流成功完成(oauth_tokens.json 存在）

可用的MCP工具

配置后，您可以在Cursor中使用这些工具：

  • get_projects -获取所有Basecamp项目
  • get_project -获取特定项目的详细信息
  • get_todolists -获取项目的待办事项列表
  • get_todos -从待办事项列表中获取待办事项
  • search_basecamp -跨项目、待办事项和消息搜索
  • get_comments -获取Basecamp项目的评论
  • get_campfire_lines -获取Basecamp篝火的最新消息
  • get_daily_check_ins -获取项目的每日登记问题
  • get_question_answers -获取每日入住问题的答案
  • create_attachment -上传文件作为附件
  • get_events -获取事件以进行录制
  • get_webhooks - 列出项目的 webhooks
  • create_webhook - 创建一个网钩
  • delete_webhook - 删除网钩
  • get_documents -列出vault中的文档
  • get_document -获取单个文档
  • create_document -创建文档
  • update_document -更新文档
  • trash_document -将文档移至回收站

卡片表格工具

  • 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 -将卡片步骤标记为未完成

光标使用示例

询问Cursor以下问题：

  • “显示我的所有Basecamp项目”
  • “X项目中有哪些待办事项？”
  • “搜索包含“截止日期”的邮件”
  • “获取技术项目的详细信息”
  • “显示项目X的卡片表”
  • 在“进行中”列中创建新卡
  • “将此卡移至“完成”列”
  • “将“紧急”列的颜色更新为红色”
  • “将卡片标记为完整”
  • “显示此卡的所有步骤”
  • “为此卡创建子任务”
  • “将此卡步骤标记为完成”

建筑

该项目使用 官方@modelcontextprotocol/sdk 为了获得最大的可靠性和兼容性：

  1. MCP服务器 (src/index.ts)-官方MCP SDK，包含46个工具，兼容Cursor和Claude Desktop
  2. OAuth应用程序 (src/lib/oauth-app.ts)-使用Basecamp处理OAuth 2.0流
  3. 令牌存储 (src/lib/token-storage.ts)-安全地存储OAuth令牌
  4. Basecamp客户 (src/lib/basecamp-client.ts)-Basecamp API客户库
  5. 类型定义 (src/types/basecamp.ts)-完整的TypeScript接口
  6. 配置脚本:
    • 用于设置、身份验证和配置生成的NPM脚本
    • 内置TypeScript编译和测试

故障排除

常见问题（双方客户）

  • 🔴 红色/黄色指示器： 跑 npm run setup 构建项目及其依赖关系
  • 🔴 “0个可用工具”： 项目未构建或缺少依赖项-运行安装脚本
  • 🔴 “找不到工具”错误： 完全重新启动客户端（Cursor/Claude Desktop）
  • ⚠️ 缺少BASECAMP_ACCOUNT_ID： 增添 .env 文件，然后重新运行配置生成器

快速修复

问题：服务器无法启动

# Test if MCP server works:
node dist/index.js
# If this fails, run: npm run build

问题：Node.js版本错误

node --version  # Must be 18+
# If too old, install newer Node.js and re-run setup

问题：身份验证失败

# Check OAuth flow:
npm run auth
# Visit http://localhost:8000 and complete login

手动配置（最后手段）

光标配置位置： ~/.cursor/mcp.json （macOS/Linux）或 %APPDATA%\Cursor\mcp.json （Windows）
Claude桌面配置位置： ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）

{
    "mcpServers": {
        "basecamp": {
            "command": "node",
            "args": ["/full/path/to/your/project/dist/index.js"],
            "cwd": "/full/path/to/your/project",
            "env": {
                "BASECAMP_ACCOUNT_ID": "your_account_id"
            }
        }
    }
}

查找您的帐户ID

如果您不知道您的Basecamp帐户ID：

  1. 在浏览器中登录Basecamp
  2. 看看URL——它会像 https://3.basecamp.com/4389629/projects
  3. 号码（本例中为4389629）是您的帐户ID

安全说明

  • 保持你的 .env 文件安全，从不将其提交到版本控制
  • OAuth令牌存储在本地 oauth_tokens.json
  • 此设置专为本地开发使用而设计

致谢

这个TypeScript实现的灵感来自并建立在原始版本提供的优秀基础之上 python Basecamp MCP服务器.

非常感谢。 感谢最初的Python项目维护者为实现这种TypeScript改编奠定了坚实的基础！ 🙏

许可证

该项目根据MIT许可证获得许可。

相关 MCP