georgeantonopoulos/Basecamp-MCP-Server

An MCP server for Basecamp 3. It lets MCP-capable clients such as Codex, Cursor, and Claude Desktop read and manage Basecamp projects through OAuth-authenticated Basecamp API calls.
The main server is basecamp_fastmcp.py. It uses the official mcp.server.fastmcp Python SDK and exposes 79 tools covering projects, todos, message boards, campfires, card tables, inbox forwards, documents, uploads, comments, events, webhooks, and search.
What It Can Do
- Browse Basecamp projects and project details.
- Search across projects, todos, messages, campfire lines, comments, uploads, and schedules.
- Read and manage todolists, todos, todo groups, and completion state.
- Read and create message board messages, including drafts and categories.
- Read campfire lines.
- Read and create comments.
- Work with card tables, columns, cards, and card steps.
- Read inbox forwards and replies.
- Read daily check-ins and answers.
- Upload attachments and inspect uploads.
- Read and manage documents, including drafts.
- List events and manage webhooks.
- Generate local MCP configuration for Codex, Cursor, and Claude Desktop.
Requirements
- Python 3.10 or newer.
- A Basecamp 3 account.
- A Basecamp OAuth application from .
- A client that can run local MCP servers, such as Codex, Cursor, or Claude Desktop.
If your system Python is older, use uv; it can create a virtual environment with a newer Python version.
Quick Start
Clone the repository and install dependencies:
Or, if python already points to Python 3.10 or newer:
Create a .env file from the example and fill in your Basecamp OAuth details:
Required values:
Authenticate with Basecamp:
Open and complete the OAuth flow. The token is stored locally in oauth_tokens.json by default.
Configure Your MCP Client
Codex
Useful options:
The script writes a basecamp server entry to ~/.codex/config.toml and points it at this checkout's virtual environment and basecamp_fastmcp.py.
Cursor
Then restart Cursor and check Settings -> MCP. The server should appear as basecamp.
Claude Desktop
Then fully quit and reopen Claude Desktop. The generated config is written to:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: ~/AppData/Roaming/Claude/claude_desktop_config.json
- Linux: ~/.config/claude-desktop/claude_desktop_config.json
Verify The Server
Run the FastMCP server through stdio and ask for its tool list:
Run the automated tests:
Available Tools
The FastMCP server exposes 82 tools.
Projects And Search
- get_projects
- get_project
- search_basecamp
- global_search
Reports
- get_assignable_people — all people who can have to-dos assigned to them
(GET /reports/todos/assigned.json)
- get_person_assignments — all active, pending to-dos assigned to one
person across **all** projects (GET /reports/todos/assigned/{id}.json,
optional group_by: bucket|date). Prefer this over iterating projects
when you need everything assigned to a single person.
- get_overdue_todos — all overdue to-dos across all projects, grouped by
lateness (GET /reports/todos/overdue.json)
Todos
- get_todolists
- get_todolist
- create_todolist
- update_todolist
- trash_todolist
- get_todos
- get_todo
- create_todo
- update_todo
- delete_todo
- archive_todo
- complete_todo
- uncomplete_todo
- reposition_todo
- get_todolist_groups
- create_todolist_group
- reposition_todolist_group
Messages, Campfires, And Check-Ins
- get_message_board
- get_messages
- get_message
- get_message_categories
- create_message
- create_draft_message
Pass publish: false to create_message to create a draft message instead
of posting it immediately. Agents can also call create_draft_message directly
when the intended operation is specifically to create a draft.
- get_campfire_lines