Basecamp-MCP-Server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a Basecamp 3 MCP (Model Context Protocol) Server that allows AI assistants (Cursor, Claude Desktop) to interact with Basecamp directly. It uses OAuth 2.0 for authentication and provides 79 tools for Basecamp operations.

Development Commands

# Setup (one-time) - requires Python 3.10+
# Option 1: Using uv (recommended - auto-downloads Python 3.12)
uv venv --python 3.12 venv && source venv/bin/activate && uv pip install -r requirements.txt && uv pip install mcp

# Option 2: Using pip (if Python 3.10+ already installed)
python setup.py                      # Creates venv, installs deps, tests server

# OAuth Authentication
python oauth_app.py                  # Start OAuth server at http://localhost:8000

# Run the MCP server (for testing)
./venv/bin/python basecamp_fastmcp.py    # FastMCP server (recommended)
./venv/bin/python mcp_server_cli.py      # Legacy CLI server

# Test the server manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | python basecamp_fastmcp.py

# Run tests
python -m pytest tests/ -v           # All tests
python -m pytest tests/test_cli_server.py -v  # Specific test file

# Generate client configs
python generate_cursor_config.py           # For Cursor IDE
python generate_claude_desktop_config.py   # For Claude Desktop

Architecture

Core Files

File	Purpose
basecamp_fastmcp.py	Main MCP server using official Anthropic FastMCP framework (79 tools)
mcp_server_cli.py	Legacy JSON-RPC server (same tools, custom implementation)
basecamp_client.py	Basecamp 3 API client - all HTTP methods and endpoints
basecamp_oauth.py	OAuth 2.0 client for 37signals Launchpad
auth_manager.py	Automatic token refresh before API calls
token_storage.py	Thread-safe OAuth token persistence. Path defaults to <project>/oauth_tokens.json; override with BASECAMP_MCP_TOKEN_FILE env var
search_utils.py	Cross-project search functionality
oauth_app.py	Flask app for OAuth flow (browser-based login)