Basecamp MCP

🚀 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

📦 Installation

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__*"
  ]
}

🚀 Quick Start

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

💻 Usage Examples

Basic Usage

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

📚 Documentation

Available Tools

Projects

To-dos

Messages

Comments

People

Schedules

Documents

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.