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.

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

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

\ 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

People

Todo Lists

Todos

Messages & Topics

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