Basecamp MCP Server

大本营MCP集成

该项目提供了 FastMCP供电 Basecamp 3的集成，允许AI客户端通过MCP协议直接与Basecamp交互。

✅ 迁移完成： 已成功迁移到官方Anthropic FastMCP框架 100%特征奇偶校验 （全部75个工具） 🚀 准备生产： 完全符合MCP 2025-06-18的协议

快速设置

此服务器与 光标, 法典，以及 克劳德桌面。选择您的首选客户：

先决条件

• Python 3.10+ （MCP SDK需要）--或使用 uv 哪个自动下载正确的版本
• Basecamp 3帐户
• Basecamp OAuth应用程序（在 )

对于游标用户

一个命令设置

1. 克隆并设置uv（推荐）：

   git clone 
   cd Basecamp-MCP-Server

   # Using uv (recommended - auto-downloads Python 3.12)
   uv venv --python 3.12 venv
   source venv/bin/activate  # or venv\Scripts\activate on Windows
   uv pip install -r requirements.txt
   uv pip install mcp

替代方案：使用pip （需要已安装Python 3.10+）：

   python setup.py

自动设置：

- ✅ 创建虚拟环境 - ✅ 安装所有依赖项（FastMCP SDK等） - ✅ 创造 .env 模板文件 - ✅ 测试MCP服务器功能

1. 配置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)"

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

   python oauth_app.py

访问 并完成OAuth流程。

1. 生成游标配置：

   python generate_cursor_config.py

1. 完全重新启动游标 （退出并重新打开，而不仅仅是重新加载）

1. 在游标中验证：

- 转到光标设置→ MCP - 你应该看看“大本营” 绿色复选标记 - 可用工具： 75工具 实现完整的大本营控制

测试您的设置

# Quick test the FastMCP server (works with both clients)
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":{}}' | python basecamp_fastmcp.py

# Run automated tests  
python -m pytest tests/ -v

适用于Codex用户

Codex集成是完全自动化的，使用与本地路径无关的脚本。 该脚本计算此存储库根的所有路径，因此无论存储库安装在哪里，它都能正常工作。

设置步骤

1. 完成基本设置 （与上述光标步骤1-3相同）：

   git clone 
   cd Basecamp-MCP-Server
   python setup.py
   # Configure .env file with OAuth credentials
   python oauth_app.py

1. 自动生成Codex配置：

   python generate_codex_config.py

可选标志：

   # Preview commands only (no changes):
   python generate_codex_config.py --dry-run

   # Use legacy server instead of FastMCP:
   python generate_codex_config.py --legacy

1. 在Codex中验证：

   codex mcp get basecamp
   codex mcp list

Codex配置

脚本写入Codex全局配置：

• ~/.codex/config.toml

它创建了此MCP服务器条目形状：

[mcp_servers.basecamp]
command = "/path/to/your/project/venv/bin/python"
args = ["/path/to/your/project/basecamp_fastmcp.py"]

[mcp_servers.basecamp.env]
PYTHONPATH = "/path/to/your/project"
VIRTUAL_ENV = "/path/to/your/project/venv"
BASECAMP_ACCOUNT_ID = "your_account_id"

适用于Claude桌面用户

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

设置步骤

1. 完成基本设置 （上述光标设置的步骤1-3）：

   git clone 
   cd Basecamp-MCP-Server
   python setup.py
   # Configure .env file with OAuth credentials
   python oauth_app.py

1. 生成Claude桌面配置：

   python generate_claude_desktop_config.py

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

1. 在Claude Desktop中验证：

- 查找“搜索和工具”图标(🔍) 在聊天界面中 - 你应该看到“大本营”列出了所有75种可用工具 - 打开工具以启用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": "/path/to/your/project/venv/bin/python",
      "args": ["/path/to/your/project/basecamp_fastmcp.py"],
      "env": {
        "PYTHONPATH": "/path/to/your/project",
        "VIRTUAL_ENV": "/path/to/your/project/venv",
        "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
• 连接失败：检查Python路径和脚本路径是否为绝对路径
• 身份验证错误：确保OAuth流成功完成（令牌文件存在--请参阅 令牌存储位置)

可用的MCP工具

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

• get_projects -获取所有Basecamp项目
• get_project -获取特定项目的详细信息
• get_todolists -获取项目的待办事项列表
• get_todolist -按ID获取特定待办事项列表
• create_todolist -在项目中创建新的待办事项列表
• update_todolist -更新现有待办事项列表（姓名和/或描述）
• trash_todolist -将待办事项列表移至回收站（可在30天内恢复）
• get_todos -从待办事项列表中获取待办事项（返回所有页面；透明地处理Basecamp分页）
• get_todo -按ID获取单个待办事项
• create_todo -在待办事项列表中创建一个新的待办事项（包括指定人员、截止日期、描述）
• update_todo -更新现有待办事项（内容、描述、受让人、截止日期等）
• delete_todo -将待办事项移至回收站（可在30天内恢复）
• complete_todo -将待办事项标记为已完成
• uncomplete_todo -将待办事项标记为不完整
• reposition_todo -在待办事项列表中重新定位待办事项，或将其移动到另一个列表或组中
• archive_todo -存档待办事项（隐藏在活动列表中，可通过web UI访问）
• search_basecamp -跨项目、待办事项和消息搜索
• global_search -在所有项目中搜索项目、待办事项和篝火消息
• get_comments -获取Basecamp项目的评论
• create_comment -对Basecamp项目创建评论
• get_campfire_lines -获取Basecamp篝火的最新消息
• get_message_board -获取项目的留言板
• get_messages -从项目的留言板获取所有消息
• get_message -按ID获取特定消息
• get_message_categories -获取项目的可用消息类别（类型）（例如公告、仅供参考、心跳、音调、问题）
• create_message -在项目的留言板上创建一条带有可选类别的新消息
• get_daily_check_ins -获取项目的每日登记问题
• get_question_answers -获取每日入住问题的答案
• create_attachment -上传文件作为附件
• get_uploads -列出项目或vault中的上载
• get_upload -获取特定上传的详细信息
• get_events -获取事件以进行录制
• get_webhooks -列出项目的webhooks
• create_webhook -创建webhook
• delete_webhook -删除webhook
• get_documents -列出vault中的文档
• get_document -获取单个文档
• create_document -创建文档
• update_document -更新文档
• trash_document -将文档移至回收站

待办事项列表组工具

• get_todolist_groups -获取待办事项列表中的所有组（命名部分，如“第一阶段”、“待办事项”）
• create_todolist_group -在待办事项列表中创建一个新组（支持颜色：白色、红色、橙色、黄色、绿色、蓝色、水绿色、紫色、灰色、粉色、棕色）
• reposition_todolist_group -将待办事项列表组重新定位到其列表中的新位置

收件箱工具（电子邮件转发）

• get_inbox -获取项目的收件箱（电子邮件转发容器）
• get_forwards -从项目收件箱获取所有转发的电子邮件
• get_forward -按ID获取特定转发的电子邮件
• get_inbox_replies -获取转发电子邮件的所有回复
• get_inbox_reply -获取转发电子邮件的特定回复
• trash_forward -将转发的电子邮件移至垃圾箱

卡片表格工具

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

光标使用示例

询问Cursor以下问题：

• “显示我的所有Basecamp项目”
• “X项目中有哪些待办事项？”
• “在Sprint待办事项列表中创建一个新的待办事项‘审查PR’”
• “将‘部署v2’待办事项标记为完成”
• “显示项目X中留言板上的消息”
• “项目X中有哪些可用的消息类别？”
• “在项目X的留言板上发布新的公告：‘我们发布了v2.0！’”
• “在项目X中创建每周进度更新的心跳消息”
• “搜索包含“截止日期”的邮件”
• “获取技术项目的详细信息”
• “显示项目X的卡片表”
• 在“进行中”列中创建新卡
• “将此卡移至“完成”列”
• “将“紧急”列的颜色更新为红色”
• “将卡片标记为完整”
• “显示此卡的所有步骤”
• “为此卡创建子任务”
• “将此卡步骤标记为完成”

建筑

该项目使用 官方Anthropic FastMCP框架 为了获得最大的可靠性和兼容性：

1. FastMCP服务器 (basecamp_fastmcp.py)-官方MCP SDK，包含75个工具，与Cursor、Codex和Claude Desktop兼容
2. OAuth应用程序 (oauth_app.py)-使用Basecamp处理OAuth 2.0流
3. 令牌存储 (token_storage.py)-安全地存储OAuth令牌
4. Basecamp客户 (basecamp_client.py)-Basecamp API客户库
5. 搜索实用程序 (search_utils.py)-搜索Basecamp资源
6. 设置自动化 (setup.py)-一个命令安装
7. 配置生成器:

- generate_cursor_config.py -用于Cursor IDE集成 - generate_codex_config.py -用于Codex CLI集成 - generate_claude_desktop_config.py -用于Claude Desktop集成

故障排除

常见问题（双方客户）

• 🔴 红色/黄色指示器： 跑 python setup.py 创建适当的虚拟环境
• 🔴 “0个可用工具”： 虚拟环境缺少MCP包-运行安装脚本
• 🔴 “找不到工具”错误： 完全重新启动您的客户端（游标/Codex/Claude桌面）
• ⚠️ 缺少BASECAMP_ACCOUNT_ID： 添加 .env 文件，然后重新运行配置生成器

快速修复

问题：服务器无法启动

# Test if FastMCP server works:
./venv/bin/python -c "import mcp; print('✅ MCP available')"
# If this fails, run: python setup.py

问题：Python版本错误

python --version  # Must be 3.10+
# If too old, use uv which auto-downloads the correct Python:
uv venv --python 3.12 venv && source venv/bin/activate && uv pip install -r requirements.txt && uv pip install mcp

问题：身份验证失败

# Check OAuth flow:
python oauth_app.py
# Visit http://localhost:8000 and complete login

手动配置（最后手段）

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

{
    "mcpServers": {
        "basecamp": {
            "command": "/full/path/to/your/project/venv/bin/python",
            "args": ["/full/path/to/your/project/basecamp_fastmcp.py"],
            "cwd": "/full/path/to/your/project",
            "env": {
                "PYTHONPATH": "/full/path/to/your/project",
                "VIRTUAL_ENV": "/full/path/to/your/project/venv",
                "BASECAMP_ACCOUNT_ID": "your_account_id"
            }
        }
    }
}

食品法典等效物：

[mcp_servers.basecamp]
command = "/full/path/to/your/project/venv/bin/python"
args = ["/full/path/to/your/project/basecamp_fastmcp.py"]

[mcp_servers.basecamp.env]
PYTHONPATH = "/full/path/to/your/project"
VIRTUAL_ENV = "/full/path/to/your/project/venv"
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 （600个权限，以及 token_storage.py)
• 此设置专为本地开发使用而设计

令牌存储位置

默认情况下，OAuth令牌文件位于 token_storage.py ( /oauth_tokens.json).对于项目目录为只读或临时的容器化或服务器部署，请设置 BASECAMP_MCP_TOKEN_FILE 将环境变量转换为绝对路径：

export BASECAMP_MCP_TOKEN_FILE=/var/lib/basecamp-mcp/oauth_tokens.json

路径在导入时解析；OAuth应用程序和MCP服务器都支持相同的变量，因此它们保持同步，没有符号链接或文件副本。未设置时，行为不变。

token_storage.py 也试图 chmod 令牌文件 0o600 写时（尽最大努力；在不支持它的平台上跳过，如Windows）。如果你指出 BASECAMP_MCP_TOKEN_FILE 在共享或挂载位置，确保父目录权限也适当，因为只有令牌文件本身是chmod’d。

许可证

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

明星历史