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.