Basecamp MCP Server

Connect your Basecamp workspace to Claude and other AI tools via the Model Context Protocol.

Setup

1. Get Basecamp API Credentials

Go to Basecamp and log in
Click your profile → "Settings" → "Personal access tokens" (or "Integrations & apps" → "API credentials")
Create a new token (it needs "all access")
Copy the token
Find your Account ID in the URL when you're in your workspace (e.g., https://3.basecamp.com/ACCOUNT_ID)

2. Set Environment Variables

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

Or create a .env file in the project root (add to .gitignore):

BASECAMP_API_TOKEN=your_token_here
BASECAMP_ACCOUNT_ID=your_account_id_here

3. Install Dependencies

uv sync

4. Run the Server

uv run python -m basecamp_mcp.server

Or run it directly:

uv run python src/basecamp_mcp/server.py

Features

Tools (Functions Claude Can Call)

get_projects - List all Basecamp projects
get_project_details - Get detailed info about a project
get_messages - Get recent messages from a project
get_message_with_comments - Get a specific message with all comments
get_todos - Get todo items (with optional filtering by completion)
create_message - Create a new message in a project
update_todo - Mark a todo as complete/incomplete
get_schedules - Get schedules from a project
clear_cache - Clear all cached data
get_cache_stats - View cache statistics

Resources (Data Claude Can Read)

basecamp://projects - List of all projects
basecamp://project/{project_id}/summary - Project summary with recent activity

Caching

The server uses SQLite for persistent caching with TTL (Time To Live):

Projects: 5 minutes cache
Messages: 2 minutes cache
Todos: 2 minutes cache
Project details: 10 minutes cache

Use get_cache_stats to see cache hit rates and size, or clear_cache to force fresh data.

Project Structure

BaseCampMCP/
├── src/
│   └── basecamp_mcp/
│       ├── __init__.py
│       ├── server.py       # Main MCP server with tools & resources
│       └── cache.py        # SQLite cache manager
├── pyproject.toml          # Project configuration
└── README.md

Integration with Claude Desktop

To use with Claude Desktop:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the Windows equivalent
Add the server:

{
  "mcpServers": {
    "basecamp": {
      "command": "uv",
      "args": ["run", "--with", "mcp", "python", "-m", "basecamp_mcp.server"],
      "cwd": "/Users/kaustubh/Documents/BaseCampMCP"
    }
  }
}

Restart Claude Desktop

Development

Testing the Server

# Run with verbose logging
uv run python -m basecamp_mcp.server

Viewing Cache

The cache database is stored in basecamp_cache.db in your working directory. You can inspect it with:

sqlite3 basecamp_cache.db
sqlite> SELECT key, hits, expires_at FROM cache ORDER BY hits DESC;

API Reference

Basecamp API v1 Endpoints Used

GET /projects.json - List projects
GET /projects/{id}.json - Get project details
GET /projects/{id}/messages.json - List messages
GET /projects/{id}/messages/{message_id}.json - Get message
GET /projects/{id}/messages/{message_id}/comments.json - Get comments
GET /projects/{id}/todos.json - List todos
GET /projects/{id}/todolists/{list_id}/todos.json - Get todos from list
PUT /projects/{id}/todos/{todo_id}.json - Update todo
POST /projects/{id}/messages.json - Create message
GET /projects/{id}/schedules.json - List schedules

License

MIT