Basecamp MCP Server

An MCP (Model Context Protocol) server that provides full Basecamp 4 API access for Claude Code.

Features

• 32 tools covering the full Basecamp 4 API:

  • Projects (list, get, create, update, trash)
  • To-do Lists & To-dos (CRUD, complete/uncomplete)
  • Messages (list, get, create, update)
  • Comments (list, create, update)
  • People (list, get current user, project members)
  • Schedule Entries (list, get, create, update)
  • Documents (list, get, create, update)

• OAuth 2.0 authentication with automatic token refresh

• Rate limiting handling with retry guidance

Prerequisites

• Node.js 18+
• A Basecamp 4 account
• OAuth application credentials from Basecamp

Setup

1. Register a Basecamp OAuth Application

1. Go to https://launchpad.37signals.com/integrations
2. Click "Register your application"
3. Fill in the details:
   • Name: Claude Code MCP (or any name you prefer)
   • Website: Your website or http://localhost
   • Redirect URI: http://localhost:9876/callback
4. Save and note your Client ID and Client Secret

2. Find Your Account ID

Your Basecamp account ID is in your Basecamp URL:

https://3.basecamp.com/YOUR_ACCOUNT_ID/...

3. Set Environment Variables

Add these to your shell profile (.bashrc, .zshrc, etc.):

export BASECAMP_CLIENT_ID="your-client-id"
export BASECAMP_CLIENT_SECRET="your-client-secret"
export BASECAMP_ACCOUNT_ID="your-account-id"

4. Build the MCP Server

cd basecamp-mcp
npm install
npm run build

5. Configure Claude Code

Add the MCP server to your Claude Code configuration. Create or edit .mcp.json in your project root:

{
  "basecamp": {
    "command": "node",
    "args": ["/path/to/basecamp-mcp/dist/index.js"],
    "env": {
      "BASECAMP_CLIENT_ID": "${BASECAMP_CLIENT_ID}",
      "BASECAMP_CLIENT_SECRET": "${BASECAMP_CLIENT_SECRET}",
      "BASECAMP_ACCOUNT_ID": "${BASECAMP_ACCOUNT_ID}"
    }
  }
}

6. Add Permissions (Optional)

To auto-approve Basecamp tools, add to .claude/settings.json:

{
  "allow": [
    "mcp__basecamp__*"
  ]
}

First Run

On first use, the MCP server will:

1. Open your browser to Basecamp's authorization page
2. After you authorize, redirect to localhost:9876/callback
3. Store tokens in ~/.basecamp-mcp/tokens.json

Subsequent runs will use the stored tokens (with automatic refresh).

Available Tools

Projects

| Tool | Description | |------|-------------| | basecamp_list_projects | List all projects (optionally filter by status) | | basecamp_get_project | Get project details including dock tools | | basecamp_create_project | Create a new project | | basecamp_update_project | Update project name/description | | basecamp_trash_project | Move project to trash |

To-dos

| Tool | Description | |------|-------------| | basecamp_list_todolists | List to-do lists in a project | | basecamp_get_todolist | Get to-do list details | | basecamp_create_todolist | Create a new to-do list | | basecamp_list_todos | List to-dos in a list | | basecamp_get_todo | Get to-do details | | basecamp_create_todo | Create a to-do with assignees, due date | | basecamp_update_todo | Update a to-do | | basecamp_complete_todo | Mark to-do as complete | | basecamp_uncomplete_todo | Mark to-do as incomplete |

Messages

| Tool | Description | |------|-------------| | basecamp_list_messages | List messages on a board | | basecamp_get_message | Get message details | | basecamp_create_message | Post a new message | | basecamp_update_message | Update a message |

Comments

| Tool | Description | |------|-------------| | basecamp_list_comments | List comments on any item | | basecamp_create_comment | Add a comment | | basecamp_update_comment | Update a comment |

People

| Tool | Description | |------|-------------| | basecamp_list_people | List all people in account | | basecamp_get_person | Get person details | | basecamp_get_me | Get current user's profile | | basecamp_list_project_people | List project members |

Schedules

| Tool | Description | |------|-------------| | basecamp_list_schedule_entries | List calendar events | | basecamp_get_schedule_entry | Get event details | | basecamp_create_schedule_entry | Create a calendar event | | basecamp_update_schedule_entry | Update a calendar event |

Documents

| Tool | Description | |------|-------------| | basecamp_list_documents | List documents in vault | | basecamp_get_document | Get document content | | basecamp_create_document | Create a new document | | basecamp_update_document | Update a document |

Usage Examples

# List all projects
basecamp_list_projects

# Get project details (includes dock IDs for other tools)
basecamp_get_project project_id:12345

# Create a to-do
basecamp_create_todo project_id:12345 todolist_id:67890 content:"Review PR #123" due_on:"2024-01-20"

# Post a message
basecamp_create_message project_id:12345 message_board_id:11111 subject:"Sprint Update" content:"<p>All tasks completed!</p>"

Troubleshooting

"Missing BASECAMP_CLIENT_ID or BASECAMP_CLIENT_SECRET"

Ensure environment variables are set and exported in your shell.

"Missing BASECAMP_ACCOUNT_ID"

Find your account ID in your Basecamp URL (the number after 3.basecamp.com/).

OAuth flow doesn't complete

• Ensure port 9876 is available
• Check that the redirect URI in your Basecamp app matches exactly: http://localhost:9876/callback

Rate limiting (429 errors)

The server will report the Retry-After value. Wait and try again.

Token Storage

OAuth tokens are stored in ~/.basecamp-mcp/tokens.json with restricted permissions (600). To re-authenticate, delete this file and restart Claude Code.

API Reference

Based on the Basecamp 4 API.