Basecamp 2 MCP

A Model Context Protocol (MCP) server that connects Claude and other AI assistants to the Basecamp 2 API. Manage projects, todos, messages, and people directly from your AI assistant.

Prerequisites

• Node.js 18 or later
• A Basecamp 2 account
• OAuth 2 credentials or your username and password

OAuth Setup (recommended)

1. Register your app at launchpad.37signals.com/integrations to obtain a client_id and client_secret.

2. Run the auth helper — it opens a browser, handles the redirect, exchanges the code for tokens, and prints your BASECAMP_ACCOUNT_ID automatically:

   BASECAMP_CLIENT_ID=your_client_id \
   BASECAMP_CLIENT_SECRET=your_client_secret \
   npx basecamp-2-mcp-auth

   Copy the printed env vars into your .env or MCP server config.

3. The MCP server will automatically refresh the access token when it expires (~2 weeks) as long as BASECAMP_REFRESH_TOKEN, BASECAMP_CLIENT_ID, and BASECAMP_CLIENT_SECRET are set.

   By default npx basecamp-2-mcp-auth listens on port 3000. Set OAUTH_PORT to change it (your registered redirect URI must match).

Environment Variables

| Variable | Required | Description | |---|---|---| | BASECAMP_ACCOUNT_ID | Yes | Your account ID — printed by the auth helper, or found in the URL: basecamp.com/{account_id}/ | | BASECAMP_ACCESS_TOKEN | Yes* | OAuth 2 access token | | BASECAMP_REFRESH_TOKEN | No | Enables automatic token refresh when the access token expires | | BASECAMP_CLIENT_ID | No† | Required for automatic token refresh | | BASECAMP_CLIENT_SECRET | No† | Required for automatic token refresh | | BASECAMP_USERNAME | Yes* | Your Basecamp email (Basic Auth alternative) | | BASECAMP_PASSWORD | Yes* | Your Basecamp password (Basic Auth alternative) | | USER_AGENT | Yes | Identifies your integration, e.g. MyApp ([email protected]) |

* Either BASECAMP_ACCESS_TOKEN or both BASECAMP_USERNAME + BASECAMP_PASSWORD are required. † Required together with BASECAMP_REFRESH_TOKEN to enable automatic token refresh.

Setup with Claude Desktop

Add the following to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "basecamp-2": {
      "command": "npx",
      "args": ["-y", "basecamp-2-mcp"],
      "env": {
        "BASECAMP_ACCOUNT_ID": "your_account_id",
        "BASECAMP_ACCESS_TOKEN": "your_access_token",
        "BASECAMP_REFRESH_TOKEN": "your_refresh_token",
        "BASECAMP_CLIENT_ID": "your_client_id",
        "BASECAMP_CLIENT_SECRET": "your_client_secret",
        "USER_AGENT": "MyApp ([email protected])"
      }
    }
  }
}

Then restart Claude Desktop.

Setup with Claude Code

claude mcp add basecamp-2 -- npx -y basecamp-2-mcp

Then set the required environment variables in your shell or .env file.

Running Locally

# 1. Clone the repo and install dependencies
npm install

# 2. Copy and fill in environment variables
cp .env.example .env

# 3. Build
npm run build

# 4. Start the MCP server
npm start

For development with live reload:

npm run dev

To test interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector npx tsx src/index.ts

Available Tools

Projects

| Tool | Description | |---|---| | list_projects | List all active projects | | get_project | Get a project by ID |

People

| Tool | Description | |---|---| | get_me | Get the currently authenticated user | | list_people | List all people in the account | | get_person | Get a person by ID |

Todo Lists

| Tool | Description | |---|---| | list_todolists | List all todo lists in a project | | get_todolist | Get a todo list with its todos | | create_todolist | Create a new todo list in a project |

Todos

| Tool | Description | |---|---| | list_todos | List all todos in a todo list | | get_todo | Get a single todo item | | create_todo | Create a new todo (supports due date + assignee) | | update_todo | Update a todo's content, due date, or assignee | | complete_todo | Mark a todo as completed | | delete_todo | Delete a todo item |

Messages & Topics

| Tool | Description | |---|---| | list_topics | List all topics (messages, forwards, etc.) in a project | | get_message | Get a full message by ID (use the topicable.id from list_topics) | | create_message | Post a new message to a project |

Authentication

Basecamp 2 uses OAuth 2 via Launchpad. The authorization flow is:

1. User visits https://launchpad.37signals.com/authorization/new?type=web_server&client_id=…&redirect_uri=…
2. After approving, Basecamp redirects to your redirect_uri with a short-lived code
3. Your app POSTs the code to https://launchpad.37signals.com/authorization/token to receive an access token and a refresh token
4. Access tokens are sent as Authorization: Bearer <token>. Refresh tokens last ~2 weeks.

The npx basecamp-2-mcp-auth helper handles steps 1–3 automatically. The MCP server handles step 4 including silent refresh.

Every API request must also include a User-Agent header identifying your app and a contact email — this is a Basecamp API requirement. See Identifying your application.

License

MIT