Basecamp MCP Server

Português (Brasil)

An open-source Model Context Protocol server for Basecamp projects, messages, to-dos, recordings, and Card Tables. It is designed for operational workflows where an AI assistant needs to retrieve context, prepare changes, and keep sensitive card mutations behind explicit, preview-bound approval.

Highlights

• Discover projects and enabled project tools.

• Search to-dos and Card Table cards by title or assignee.

• Follow Basecamp pagination automatically.

• Keep mutation tools disabled by default.

• Preview sensitive card updates before writing.

• Bind card comments, due-date changes, and investigation reports to short-lived, single-use confirmation tokens.

• Refuse ambiguous title-based writes when multiple items match.

• Support OAuth authorization and token refresh.

• Run linting, typing, tests, and dependency auditing in CI.

Related MCP server: Basecamp MCP Server

How preview-bound confirmation works

Sensitive Card Table workflows use a two-step protocol:

1. Call a preview tool.

2. Show the preview to the user.

3. The preview returns a short-lived confirmation_id bound to the exact card and payload.

4. After explicit approval, call the matching write tool with that confirmation_id.

5. The server verifies that the requested write exactly matches the approved preview and consumes the token.

A confirmation token cannot be reused and cannot authorize a changed payload.

Requirements

• Python 3.11 or newer.

• A Basecamp OAuth application or valid access token.

• An MCP-compatible stdio client such as Kiro, Claude Desktop, or another MCP host.

Install from GitHub

uv tool install git+https://github.com/thiagorchaves/basecamp-mcp-server.git

For development:

git clone https://github.com/thiagorchaves/basecamp-mcp-server.git
cd basecamp-mcp-server
uv sync --extra dev

Configure Basecamp OAuth

Register an application in the 37signals integrations console and use this redirect URI:

http://localhost:8000/callback

Create your local environment file:

cp .env.example .env
chmod 600 .env

Set at least:

BASECAMP_CLIENT_ID=your_oauth_client_id
BASECAMP_CLIENT_SECRET=your_oauth_client_secret
BASECAMP_REDIRECT_URI=http://localhost:8000/callback
BASECAMP_USER_AGENT=Basecamp MCP Server (you@example.com)

Authorize the application:

basecamp-oauth

Refresh an expired access token with:

basecamp-oauth --refresh

Test the connection:

basecamp-test

Write safety

Mutation tools are not registered unless this variable is enabled:

BASECAMP_ENABLE_WRITE_TOOLS=true

Keep it false for read-only usage. Even when writes are enabled, do not add mutation tools to an MCP client's automatic approval list.

Preview-bound confirmation tokens default to five minutes:

BASECAMP_CONFIRMATION_TTL_SECONDS=300

The following Card Table writes require a valid preview token:

• add_card_update from preview_card_update

• update_card_due_date from preview_card_due_date

• add_investigation_report_to_card from preview_investigation_report_to_card

Other optional mutation tools still rely on BASECAMP_ENABLE_WRITE_TOOLS=true and the MCP host's approval controls.

Kiro configuration

{
  "mcpServers": {
    "basecamp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/thiagorchaves/basecamp-mcp-server.git",
        "basecamp-mcp"
      ],
      "env": {
        "BASECAMP_ACCOUNT_ID": "${BASECAMP_ACCOUNT_ID}",
        "BASECAMP_ACCESS_TOKEN": "${BASECAMP_ACCESS_TOKEN}",
        "BASECAMP_USER_AGENT": "${BASECAMP_USER_AGENT}",
        "BASECAMP_ENABLE_WRITE_TOOLS": "false",
        "BASECAMP_CONFIRMATION_TTL_SECONDS": "300"
      },
      "autoApprove": []
    }
  }
}

Tools

Read-only and preview

• healthcheck

• list_projects, find_projects, find_project_by_name, get_project

• get_project_tools

• list_messages

• list_todolists, list_project_todolists, list_todos

• list_project_todos, find_todos_by_title

• get_recording

• list_project_card_tables, get_card_table, list_cards

• find_cards_by_title, find_cards_by_assignee, get_my_cards

• preview_card_update

• preview_card_due_date

• preview_investigation_report_to_card

Write-enabled

• create_message, create_project_message

• create_project_message_from_markdown

• create_todo, create_todo_from_markdown

• update_card_by_title

• add_comment, comment_recording_from_markdown

• add_card_update (preview token required)

• update_card_due_date (preview token required)

• add_investigation_report_to_card (preview token required)

Recommended card workflow

1. Find the project and target card.

2. Display its title, column, URL, and current state.

3. Call the appropriate preview tool.

4. Show the preview and ask the user for explicit confirmation.

5. Pass the returned confirmation_id to the matching write tool.

6. Read the resource again and report the final state.

Development

uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run mypy basecamp_mcp
uv run pytest

CI tests Python 3.11, 3.12, and 3.13 and runs a scheduled dependency audit.

Security

Never commit .env, OAuth tokens, account IDs from private environments, or real API responses containing people and project data. See SECURITY.md for vulnerability reporting.

License

MIT. See LICENSE.