Basecamp

This MCP server lets you connect your Basecamp workspace to Claude and other AI tools using the Model Context Protocol. It provides a set of programmable actions to read and write Basecamp data, cache results for fast responses, and expose clear resources for your AI workflows.

How to use

You use this server with an MCP client to access Basecamp data and perform common actions. Start by authenticating with your Basecamp account, then run the server locally or connect to it from your MCP client. You will interact with the available tools to list projects, read messages, manage todos, and create or update items as needed. The server exposes data through resources Claude can read and specific tools Claude can call to perform actions.

Practical usage patterns include listing all projects, viewing details for a single project, fetching recent messages, reading messages with their comments, listing and updating todos, and retrieving schedules. You can also clear the server cache or inspect cache statistics to monitor performance.

How to install

Prerequisites: you need Python installed on your system and access to run commands from your shell. You will also use a lightweight command runner to start the MCP server.

1. Get your Basecamp API credentials from your Basecamp workspace. You need an all-access personal access token and your account ID.

2. Set environment variables (examples shown). You can export them in your shell or place them in a .env file in your project root.

export BASECAMP_API_TOKEN="your_token_here"
export BASECAMP_ACCOUNT_ID="your_account_id_here"

BASECAMP_API_TOKEN=your_token_here
BASECAMP_ACCOUNT_ID=your_account_id_here

3. Install dependencies or ensure the runtime supports MCP execution. The server uses the UV-based runner in the examples.

4. Start the MCP server using one of the provided run commands.

uv run python -m basecamp_mcp.server

uv run python src/basecamp_mcp/server.py

Configuration and environment

The server relies on two environment variables to access Basecamp data. Provide these values before starting the server.

Environment variables you set define how the server authenticates and which Basecamp account to access.

Caching and data access

The server uses SQLite for persistent caching, with TTLs to balance freshness and performance. Typical cache TTLs are 5 minutes for projects, 2 minutes for messages and todos, and 10 minutes for project details. You can inspect cache statistics and clear the cache to force fresh data.

Project structure

The project layout includes the MCP server code, a cache module, and configuration files. The main server entrypoint and cache are located under the src/basecamp_mcp package.

Integration notes

If you are integrating with Claude Desktop or other clients, use the standard MCP connection flow to point the client at your local server. Start the server with one of the accepted commands, then configure your MCP client to connect to that local instance.

Troubleshooting and tips

If you encounter authentication issues, double-check your BASECAMP_API_TOKEN and BASECAMP_ACCOUNT_ID values. Ensure there are no extra spaces and that the token has the necessary permissions. If the server cannot reach Basecamp, verify network access from your runtime environment.

Available tools

get_projects

List all Basecamp projects that you have access to.

get_project_details

Fetch detailed information for a specific Basecamp project.

get_messages

Retrieve recent messages from a project.

get_message_with_comments

Get a specific message along with all its comments.

get_todos

List todo items for a project, with optional completion filtering.

create_message

Create a new message in a project.

update_todo

Mark a todo item as complete or incomplete.

get_schedules

Retrieve schedules for a project.

clear_cache

Clear all cached data.

get_cache_stats

View statistics about the cache, including hits and size.