kbhalerao/basecamp-mcp

Basecamp MCP Server

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

Setup

1. Get Basecamp API Credentials

1. Go to Basecamp and log in
2. Click your profile → "Settings" → "Personal access tokens" (or "Integrations & apps" → "API credentials")
3. Create a new token (it needs "all access")
4. Copy the token
5. 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:

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

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

3. 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