A Model Context Protocol (MCP) server for interacting with Basecamp 4. This server enables LLMs to manage projects, to-dos, messages, schedules, comments, and files in Basecamp through a standardized interface.

• Full OAuth 2.0 authentication with token persistence and automatic refresh
• Project management - List and view projects and team members
• To-do management - Create, update, complete, and organize to-dos and to-do lists
• Messages - Post and manage messages on project message boards
• Schedule - Create and manage calendar events and schedule entries
• Comments - Add comments to any Basecamp item (messages, to-dos, files, etc.)
• File management - Upload, download, and organize files in vaults

1. Python 3.10+
2. uv (recommended) or pip
3. Basecamp OAuth application - Create one at launchpad.37signals.com/integrations

cd basecamp-mcp
uv sync

pip install -e .

Set the following environment variables:

export BASECAMP_CLIENT_ID="your_client_id"
export BASECAMP_CLIENT_SECRET="your_client_secret"
export BASECAMP_REDIRECT_URI="http://localhost:9292/callback"  # Or your callback URL
export BASECAMP_USER_AGENT="YourApp (your@email.com)"  # Required by Basecamp

# With uv
uv run basecamp-mcp

# Or directly
python -m basecamp_mcp.server

Add to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "basecamp": {
      "command": "uv",
      "args": ["--directory", "/path/to/basecamp-mcp", "run", "basecamp-mcp"],
      "env": {
        "BASECAMP_CLIENT_ID": "your_client_id",
        "BASECAMP_CLIENT_SECRET": "your_client_secret",
        "BASECAMP_USER_AGENT": "ClaudeDesktop (your@email.com)"
      }
    }
  }
}

1. Run basecamp_auth_start to get an authorization URL
2. Open the URL in a browser and authorize the application
3. Copy the code parameter from the callback URL
4. Run basecamp_auth_callback with the code
5. Run basecamp_list_accounts to see available Basecamp accounts
6. Run basecamp_set_account with the desired account ID

• basecamp_auth_start - Start OAuth flow
• basecamp_auth_callback - Complete OAuth with authorization code
• basecamp_list_accounts - List available Basecamp accounts
• basecamp_set_account - Select account to use
• basecamp_auth_status - Check authentication status

• basecamp_list_projects - List all projects
• basecamp_get_project - Get project details (including dock with tool IDs)
• basecamp_list_people - List all people in the account
• basecamp_get_person - Get person details
• basecamp_get_my_profile - Get current user's profile
• basecamp_get_project_people - List people in a project

• basecamp_get_todoset - Get the to-do set for a project
• basecamp_list_todolists - List to-do lists
• basecamp_get_todolist - Get a to-do list
• basecamp_create_todolist - Create a new to-do list
• basecamp_update_todolist - Update a to-do list
• basecamp_list_todos - List to-dos in a list
• basecamp_get_todo - Get a to-do
• basecamp_create_todo - Create a new to-do
• basecamp_update_todo - Update a to-do
• basecamp_complete_todo - Mark to-do as complete
• basecamp_uncomplete_todo - Mark to-do as incomplete
• basecamp_reposition_todo - Change to-do position

• basecamp_get_message_board - Get the message board
• basecamp_list_messages - List messages
• basecamp_get_message - Get a message
• basecamp_create_message - Post a new message
• basecamp_update_message - Update a message
• basecamp_pin_message - Pin/unpin a message
• basecamp_list_message_types - List message types

• basecamp_get_schedule - Get the schedule
• basecamp_list_schedule_entries - List schedule entries
• basecamp_get_schedule_entry - Get a schedule entry
• basecamp_create_schedule_entry - Create a new event
• basecamp_update_schedule_entry - Update an event

• basecamp_list_comments - List comments on an item
• basecamp_get_comment - Get a comment
• basecamp_create_comment - Add a comment
• basecamp_update_comment - Update a comment

• basecamp_get_vault - Get a vault (folder)
• basecamp_list_vaults - List sub-vaults
• basecamp_create_vault - Create a folder
• basecamp_list_uploads - List files in a vault
• basecamp_get_upload - Get file details
• basecamp_upload_file - Upload a file
• basecamp_update_upload - Update file description
• basecamp_get_file_download_url - Get download URL

• basecamp_search - Search across all projects
• basecamp_trash_recording - Move any item to trash

Every project has a "dock" containing its enabled tools. When you call basecamp_get_project, the response includes:

{
  "dock": [
    {"name": "message_board", "id": 123, "enabled": true},
    {"name": "todoset", "id": 456, "enabled": true},
    {"name": "schedule", "id": 789, "enabled": true},
    {"name": "vault", "id": 101, "enabled": true}
  ]
}

Use these IDs when calling tools that require message_board_id, todoset_id, schedule_id, or vault_id.

Project
└── To-do set (one per project, from dock)
    └── To-do lists
        └── To-dos

Project
└── Vault (root, from dock)
    ├── Uploads (files)
    └── Vaults (sub-folders)
        └── ...

The server handles common errors gracefully:

• 401 Unauthorized: Token expired, re-authenticate
• 404 Not Found: Resource deleted or no access
• 429 Rate Limited: Automatic retry with backoff
• 5xx Server Errors: Automatic retry with exponential backoff

Tokens are stored securely at ~/.config/basecamp_mcp/tokens.json with restrictive file permissions (600).

MIT