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 (you@example.com)

* 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 (you@example.com)"
      }
    }
  }
}

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