基地营-MCP-服务器

Name: 基地营-MCP-服务器
Author: georgeantonopoulos

作者：georgeantonopoulos42 星标更新：2025-09-12

安装使用来源：spider==github.com

项目介绍

Basecamp MCP 集成

此项目提供了一个基于FastMCP的Basecamp 3集成方案，允许Cursor通过MCP协议直接与Basecamp进行交互。

✅ 迁移完成： 成功迁移到官方Anthropic FastMCP框架，功能完全一致（所有46个工具） 🚀 生产就绪： 完全符合MCP 2025-06-18协议规范

快速设置

该服务器支持Cursor和Claude Desktop。选择您偏好的客户端：

先决条件

Python 3.8+（用于MCP SDK）
一个Basecamp 3账户
一个Basecamp OAuth应用（在https://launchpad.37signals.com/integrations创建）

对于Cursor用户

单命令设置

克隆并运行设置脚本：
```
git clone <repository-url>
cd basecamp-mcp
python setup.py
```
设置脚本会自动：
- ✅ 创建虚拟环境
- ✅ 安装所有依赖项（FastMCP SDK等）
- ✅ 创建.env模板文件
- ✅ 测试MCP服务器功能

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

使用Basecamp进行身份验证：
```
python oauth_app.py
```
访问http://localhost:8000并完成OAuth流程。
生成Cursor配置：
```
python generate_cursor_config.py
```
完全重启Cursor（退出并重新打开，不仅仅是重新加载）
在Cursor中验证：
- 前往Cursor设置 → MCP
- 您应该看到带有绿色勾号的“basecamp”
- 可用工具：46个工具以实现对Basecamp的全面控制

测试您的设置

# 快速测试FastMCP服务器（适用于两个客户端）
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

# 运行自动化测试
python -m pytest tests/ -v

对于Claude Desktop用户

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

设置步骤

完成基本设置（参照Cursor设置中的步骤1-3）：

git clone <repository-url>
cd basecamp-mcp
python setup.py
# 使用OAuth凭证配置.env文件
python oauth_app.py

生成Claude Desktop配置：

python generate_claude_desktop_config.py

完全重启Claude Desktop（退出并重新打开应用程序）
在Claude Desktop中验证：
- 查找聊天界面中的“搜索和工具”图标（🔍）
- 您应该看到列出的“basecamp”，包含所有46个可用工具
- 开启工具以启用Basecamp集成

Claude Desktop配置

配置文件自动生成于：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：~/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中的使用

询问Claude一些问题，例如：

“我当前有哪些Basecamp项目？”
“显示Technology项目的最新Campfire消息”
“在Development列创建一张标题为‘修复登录错误’的新卡片”
“获取Marketing项目的所有待办事项”
“搜索包含‘截止日期’的消息”

解决Claude Desktop的问题

检查Claude Desktop日志（参考官方调试指南）：

# macOS/Linux - 实时监控日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# 检查特定错误
ls ~/Library/Logs/Claude/mcp-server-basecamp.log

常见问题：

工具未出现：验证配置文件语法并重启Claude Desktop
连接失败：确保Python路径和脚本路径是绝对路径
认证错误：确保OAuth流程成功完成（存在oauth_tokens.json）

可用的MCP工具

一旦配置完成，您可以在Cursor中使用这些工具：

get_projects - 获取所有Basecamp项目
get_project - 获取特定项目的详细信息
get_todolists - 获取项目的待办事项列表
get_todos - 获取待办事项列表中的待办事项（返回所有页面；透明处理Basecamp分页）
search_basecamp - 跨项目、待办事项和消息搜索
get_comments - 获取Basecamp项目的评论
create_comment - 在Basecamp项目上创建评论
get_campfire_lines - 获取Basecamp Campfire的最近消息
get_daily_check_ins - 获取项目的每日检查问题
get_question_answers - 获取每日检查问题的答案
create_attachment - 上传文件作为附件
get_events - 获取录音事件
get_webhooks - 列出项目的Webhooks
create_webhook - 创建Webhook
delete_webhook - 删除Webhook
get_documents - 列出保险库中的文档
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使用

询问Cursor一些问题，例如：

“显示我所有的Basecamp项目”
“项目X有哪些待办事项？”
“搜索包含‘截止日期’的消息”
“获取Technology项目的详细信息”
“显示项目X的卡片表”
“在‘进行中’列创建一张新卡片”
“将这张卡片移动到‘完成’列”
“更新‘紧急’列的颜色为红色”
“标记卡片为已完成”
“显示这张卡片的所有步骤”
“为这张卡片创建一个子任务”
“标记这个卡片步骤为已完成”

架构

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

FastMCP服务器（basecamp_fastmcp.py）- 官方MCP SDK，包含46个工具，兼容Cursor和Claude Desktop
OAuth应用（oauth_app.py）- 处理与Basecamp的OAuth 2.0流程
令牌存储（token_storage.py）- 安全存储OAuth令牌
Basecamp客户端（basecamp_client.py）- Basecamp API客户端库
搜索工具（search_utils.py）- 跨Basecamp资源搜索
设置自动化（setup.py）- 单命令安装
配置生成器：
- generate_cursor_config.py - 用于Cursor IDE集成
- generate_claude_desktop_config.py - 用于Claude Desktop集成

故障排除

常见问题（两种客户端）

🔴 红/黄指示灯：运行python setup.py以创建正确的虚拟环境
🔴 “0个可用工具”：虚拟环境中缺少MCP包 - 运行设置脚本
🔴 “工具未找到”错误：完全重启您的客户端（Cursor/Claude Desktop）
⚠️ 缺少BASECAMP_ACCOUNT_ID：添加到.env文件，然后重新运行配置生成器

快速修复

问题：服务器无法启动

# 测试FastMCP服务器是否正常工作：
./venv/bin/python -c "import mcp; print('✅ MCP可用')"
# 如果失败，请运行：python setup.py

问题：Python版本错误

python --version  # 必须是3.8+
# 如果版本过旧，请安装较新版本的Python并重新运行设置

问题：认证失败

# 检查OAuth流程：
python oauth_app.py
# 访问http://localhost:8000并完成登录

手动配置（最后手段）

Cursor配置位置：~/.cursor/mcp.json（macOS/Linux）或%APPDATA%\Cursor\mcp.json（Windows） Claude Desktop配置位置：~/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"
            }
        }
    }
}

查找您的账户ID

如果您不知道自己的Basecamp账户ID：

在浏览器中登录Basecamp
查看URL - 它将类似于https://3.basecamp.com/4389629/projects
数字（例如这里的4389629）就是您的账户ID

安全注意事项

保护好您的.env文件，不要将其提交到版本控制系统
OAuth令牌本地存储在oauth_tokens.json中
此设置旨在用于本地开发用途

许可证

本项目根据MIT许可证发布。