Basecamp 2 MCP
Manage Basecamp 2 projects, todos, messages, and people via the Basecamp 2 API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Basecamp 2 MCP Show me my projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Basecamp MCP Server
OAuth Setup (recommended)
Register your app at launchpad.37signals.com/integrations to obtain a
client_idandclient_secret.Run the auth helper — it opens a browser, handles the redirect, exchanges the code for tokens, and prints your
BASECAMP_ACCOUNT_IDautomatically:BASECAMP_CLIENT_ID=your_client_id \ BASECAMP_CLIENT_SECRET=your_client_secret \ npx basecamp-2-mcp-authCopy the printed env vars into your
.envor MCP server config.The MCP server will automatically refresh the access token when it expires (~2 weeks) as long as
BASECAMP_REFRESH_TOKEN,BASECAMP_CLIENT_ID, andBASECAMP_CLIENT_SECRETare set.By default
npx basecamp-2-mcp-authlistens on port3000. SetOAUTH_PORTto change it (your registered redirect URI must match).
Environment Variables
Variable | Required | Description |
| Yes | Your account ID — printed by the auth helper, or found in the URL: |
| Yes* | OAuth 2 access token |
| No | Enables automatic token refresh when the access token expires |
| No† | Required for automatic token refresh |
| No† | Required for automatic token refresh |
| Yes* | Your Basecamp email (Basic Auth alternative) |
| Yes* | Your Basecamp password (Basic Auth alternative) |
| Yes | Identifies your integration, e.g. |
* 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-mcpThen 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 startFor development with live reload:
npm run devTo test interactively with the MCP Inspector:
npx @modelcontextprotocol/inspector npx tsx src/index.tsAvailable Tools
Projects
Tool | Description |
| List all active projects |
| Get a project by ID |
People
Tool | Description |
| Get the currently authenticated user |
| List all people in the account |
| Get a person by ID |
Todo Lists
Tool | Description |
| List all todo lists in a project |
| Get a todo list with its todos |
| Create a new todo list in a project |
Todos
Tool | Description |
| List all todos in a todo list |
| Get a single todo item |
| Create a new todo (supports due date + assignee) |
| Update a todo's content, due date, or assignee |
| Mark a todo as completed |
| Delete a todo item |
Messages & Topics
Tool | Description |
| List all topics (messages, forwards, etc.) in a project |
| Get a full message by ID (use the |
| Post a new message to a project |
Authentication
Basecamp 2 uses OAuth 2 via Launchpad. The authorization flow is:
User visits
https://launchpad.37signals.com/authorization/new?type=web_server&client_id=…&redirect_uri=…After approving, Basecamp redirects to your
redirect_uriwith a short-livedcodeYour app POSTs the code to
https://launchpad.37signals.com/authorization/tokento receive an access token and a refresh tokenAccess 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
Available Tools
17 toolscomplete_todoC
Mark a todo as completed
Inputs: todo_id (required), project_id (required).
create_messageB
Post a new message to a Basecamp 2 project
Inputs: body (required), subject (required), project_id (required), private.
create_todoC
Create a new todo item in a todo list
Inputs: content (required), project_id (required), todolist_id (required), due_on, +1 more.
create_todolistC
Create a new todo list in a Basecamp 2 project
Inputs: name (required), project_id (required), description.
delete_todoC
Delete a todo item
Inputs: todo_id (required), project_id (required).
get_meA
Get the currently authenticated Basecamp 2 user
Inputs: no named parameters.
get_messageB
Get a single message from a Basecamp 2 project
Inputs: message_id (required), project_id (required).
get_personA
Get a single person in the Basecamp 2 account by ID
Inputs: person_id (required).
get_projectB
Get a single Basecamp 2 project by ID
Inputs: project_id (required).
get_todoB
Get a single todo item
Inputs: todo_id (required), project_id (required).
get_todolistB
Get a single todo list with its todos
Inputs: project_id (required), todolist_id (required).
list_peopleA
List all people in the Basecamp 2 account
Inputs: no named parameters.
list_projectsA
List all active Basecamp 2 projects
Inputs: no named parameters.
list_todolistsC
List all todo lists in a Basecamp 2 project
Inputs: project_id (required).
list_todosC
List all todos in a todo list
Inputs: project_id (required), todolist_id (required).
list_topicsA
List all topics (messages, forwards, etc.) in a Basecamp 2 project
Inputs: project_id (required).
update_todoC
Update an existing todo item
Inputs: todo_id (required), project_id (required), due_on, content, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target distinct resource+action pairs (todo, todolist, project, person, message). Minor overlap exists between list_topics and get_message/create_message since messages are a subset of topics, and get_me vs get_person/list_people could momentarily confuse, but overall boundaries are clear.
Every tool follows a consistent verb_noun snake_case pattern: list_x, get_x, create_x, update_x, complete_x, delete_x. Even get_me fits the convention, making the set highly predictable.
17 tools is slightly heavy but well-scoped across five resources (projects, todolists, todos, messages, people). Each tool earns its place, with no obviously redundant entries.
Todos have full lifecycle (create/get/list/update/complete/delete), but todolists lack update/delete, messages lack update/delete (and only list_topics surfaces them), and projects lack create/update/delete. These notable gaps leave dead ends for common management workflows.
Maintenance
Related MCP Connectors
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with Basecamp projects through natural language commands. Supports managing projects, to-do lists, messages, and creating tasks with full content rendering capabilities.6ISC
- AlicenseBqualityDmaintenanceConnects Basecamp workspaces to AI tools, enabling management of projects, messages, todos, and schedules through natural language interactions. Features persistent caching and supports both reading workspace data and performing actions like creating messages and updating todos.10MIT
- AlicenseAqualityBmaintenanceEnables LLMs to interact with Basecamp projects, managing messages, todos, comments, people, and kanban boards through natural language. Supports comprehensive Basecamp operations including creating, reading, updating content with flexible output formats and URL parsing capabilities.5775 npm2MIT
- AlicenseCqualityFmaintenanceEnables AI assistants to automate Basecamp operations including project management, cards, todos, comments, and people via MCP tools.92GPL 2.0