Basecamp MCP Integration

This project provides a FastMCP-powered integration for Basecamp 3, allowing Cursor to interact with Basecamp directly through the MCP protocol.

✅ Migration Complete: Successfully migrated to official Anthropic FastMCP framework with 100% feature parity (all 46 tools)
🚀 Ready for Production: Full protocol compliance with MCP 2025-06-18

Quick Setup

This server works with both Cursor and Claude Desktop. Choose your preferred client:

Prerequisites

Python 3.10+ (required for MCP SDK) — or use uv which auto-downloads the correct version
A Basecamp 3 account
A Basecamp OAuth application (create one at https://launchpad.37signals.com/integrations)

For Cursor Users

One-Command Setup

Clone and set up with uv (recommended):
```
git clone <repository-url>
cd basecamp-mcp

# 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
```
Alternative: Using pip (requires Python 3.10+ already installed):
```
python setup.py
```
The setup automatically:
- ✅ Creates virtual environment
- ✅ Installs all dependencies (FastMCP SDK, etc.)
- ✅ Creates .env template file
- ✅ Tests MCP server functionality

Configure OAuth credentials: Edit the generated .env file:

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

Authenticate with Basecamp:
```
python oauth_app.py
```
Visit http://localhost:8000 and complete the OAuth flow.
Generate Cursor configuration:
```
python generate_cursor_config.py
```
Restart Cursor completely (quit and reopen, not just reload)
Verify in Cursor:
- Go to Cursor Settings → MCP
- You should see "basecamp" with a green checkmark
- Available tools: 46 tools for complete Basecamp control

Test Your Setup

# 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

For Claude Desktop Users

Based on the official MCP quickstart guide, Claude Desktop integration follows these steps:

Setup Steps

Complete the basic setup (steps 1-3 from Cursor setup above):

git clone <repository-url>
cd basecamp-mcp
python setup.py
# Configure .env file with OAuth credentials
python oauth_app.py

Generate Claude Desktop configuration:

python generate_claude_desktop_config.py

Restart Claude Desktop completely (quit and reopen the application)
Verify in Claude Desktop:
- Look for the "Search and tools" icon (🔍) in the chat interface
- You should see "basecamp" listed with all 46 tools available
- Toggle the tools on to enable Basecamp integration

Claude Desktop Configuration

The configuration is automatically created at:

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

Example configuration generated:

{
  "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"
      }
    }
  }
}

Usage in Claude Desktop

Ask Claude things like:

"What are my current Basecamp projects?"
"Show me the latest campfire messages from the Technology project"
"Create a new card in the Development column with title 'Fix login bug'"
"Get all todo items from the Marketing project"
"Search for messages containing 'deadline'"

Troubleshooting Claude Desktop

Check Claude Desktop logs (following official debugging guide):

# 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

Common issues:

Tools not appearing: Verify configuration file syntax and restart Claude Desktop
Connection failures: Check that Python path and script path are absolute paths
Authentication errors: Ensure OAuth flow completed successfully (oauth_tokens.json exists)

Available MCP Tools

Once configured, you can use these tools in Cursor:

get_projects - Get all Basecamp projects
get_project - Get details for a specific project
get_todolists - Get todo lists for a project
get_todos - Get todos from a todo list (returns all pages; handles Basecamp pagination transparently)
search_basecamp - Search across projects, todos, and messages
get_comments - Get comments for a Basecamp item
create_comment - Create a comment on a Basecamp item
get_campfire_lines - Get recent messages from a Basecamp campfire
get_daily_check_ins - Get project's daily check-in questions
get_question_answers - Get answers to daily check-in questions
create_attachment - Upload a file as an attachment
get_events - Get events for a recording
get_webhooks - List webhooks for a project
create_webhook - Create a webhook
delete_webhook - Delete a webhook
get_documents - List documents in a vault
get_document - Get a single document
create_document - Create a document
update_document - Update a document
trash_document - Move a document to trash

Card Table Tools

get_card_table - Get the card table details for a project
get_columns - Get all columns in a card table
get_column - Get details for a specific column
create_column - Create a new column in a card table
update_column - Update a column title
move_column - Move a column to a new position
update_column_color - Update a column color
put_column_on_hold - Put a column on hold (freeze work)
remove_column_hold - Remove hold from a column (unfreeze work)
watch_column - Subscribe to notifications for changes in a column
unwatch_column - Unsubscribe from notifications for a column
get_cards - Get all cards in a column
get_card - Get details for a specific card
create_card - Create a new card in a column
update_card - Update a card
move_card - Move a card to a new column
complete_card - Mark a card as complete
uncomplete_card - Mark a card as incomplete
get_card_steps - Get all steps (sub-tasks) for a card
create_card_step - Create a new step (sub-task) for a card
get_card_step - Get details for a specific card step
update_card_step - Update a card step
delete_card_step - Delete a card step
complete_card_step - Mark a card step as complete
uncomplete_card_step - Mark a card step as incomplete

Example Cursor Usage

Ask Cursor things like:

"Show me all my Basecamp projects"
"What todos are in project X?"
"Search for messages containing 'deadline'"
"Get details for the Technology project"
"Show me the card table for project X"
"Create a new card in the 'In Progress' column"
"Move this card to the 'Done' column"
"Update the color of the 'Urgent' column to red"
"Mark card as complete"
"Show me all steps for this card"
"Create a sub-task for this card"
"Mark this card step as complete"

Architecture

The project uses the official Anthropic FastMCP framework for maximum reliability and compatibility:

FastMCP Server (basecamp_fastmcp.py) - Official MCP SDK with 46 tools, compatible with both Cursor and Claude Desktop
OAuth App (oauth_app.py) - Handles OAuth 2.0 flow with Basecamp
Token Storage (token_storage.py) - Securely stores OAuth tokens
Basecamp Client (basecamp_client.py) - Basecamp API client library
Search Utilities (search_utils.py) - Search across Basecamp resources
Setup Automation (setup.py) - One-command installation
Configuration Generators:
- generate_cursor_config.py - For Cursor IDE integration
- generate_claude_desktop_config.py - For Claude Desktop integration

Troubleshooting

Common Issues (Both Clients)

🔴 Red/Yellow indicator: Run python setup.py to create proper virtual environment
🔴 "0 tools available": Virtual environment missing MCP packages - run setup script
🔴 "Tool not found" errors: Restart your client (Cursor/Claude Desktop) completely
⚠️ Missing BASECAMP_ACCOUNT_ID: Add to .env file, then re-run the config generator

Quick Fixes

Problem: Server won't start

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

Problem: Wrong Python version

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

Problem: Authentication fails

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

Manual Configuration (Last Resort)

Cursor config location: ~/.cursor/mcp.json (macOS/Linux) or %APPDATA%\Cursor\mcp.json (Windows)
Claude Desktop config location: ~/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"
            }
        }
    }
}

Finding Your Account ID

If you don't know your Basecamp account ID:

Log into Basecamp in your browser
Look at the URL - it will be like https://3.basecamp.com/4389629/projects
The number (4389629 in this example) is your account ID

Security Notes

Keep your .env file secure and never commit it to version control
The OAuth tokens are stored locally in oauth_tokens.json
This setup is designed for local development use

License

This project is licensed under the MIT License.

Basecamp-MCP-Server