Basecamp MCP Server

# Basecamp MCP Integration A modern **TypeScript MCP server** for Basecamp 3, providing seamless integration with Claude Desktop and Cursor IDE through the Model Context Protocol. Built with the official @modelcontextprotocol/sdk and ready for NPX installation. ✅ **TypeScript-First:** Modern, type-safe implementation with full async/await support 🚀 **NPX Ready:** Install and run with `npx @basecamp/mcp-server` ⚡ **46 API Tools:** Complete Basecamp 3 integration with all major features ## Quick Setup ### NPX Installation (Recommended) ```bash # Install and set up in one command npx jhliberty/basecamp-mcp-server setup # Authenticate with Basecamp npx jhliberty/basecamp-mcp-server auth # Configure for your AI assistant npx jhliberty/basecamp-mcp-server config claude # For Claude Desktop npx jhliberty/basecamp-mcp-server config cursor # For Cursor IDE ``` ### Prerequisites - **Node.js 18+** (required for ES modules) - A Basecamp 3 account - A Basecamp OAuth application (create one at https://launchpad.37signals.com/integrations) ## Local Development Setup ### For Development 1. **Clone and build the project:** ```bash git clone <repository-url> cd basecamp-mcp-server npm install npm run build ``` 2. **Run setup script:** ```bash npm run setup ``` The setup script automatically: - ✅ Installs all TypeScript dependencies - ✅ Builds the project to `dist/` - ✅ Creates `.env` template file - ✅ Tests MCP server functionality 3. **Configure OAuth credentials:** Edit the generated `.env` file: ```bash BASECAMP_CLIENT_ID=your_client_id_here BASECAMP_CLIENT_SECRET=your_client_secret_here BASECAMP_ACCOUNT_ID=your_account_id_here USER_AGENT="Your App Name (your@email.com)" ``` 4. **Authenticate with Basecamp:** ```bash npm run auth ``` Visit http://localhost:8000 and complete the OAuth flow. 5. **Generate configurations:** ```bash npm run config:cursor # For Cursor IDE npm run config:claude # For Claude Desktop ``` 6. **Restart your AI assistant completely** (quit and reopen) 7. **Verify in your AI assistant:** - **Cursor**: Go to Settings → MCP, look for "basecamp" with a green checkmark - **Claude Desktop**: Look for tools icon (🔍) in chat interface - Available tools: **46 tools** for complete Basecamp control ### Test Your Setup ```bash # Quick test the MCP server echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}} {"jsonrpc":"2.0","method":"notifications/initialized","params":{}} {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.js # Run automated tests npm test # Run tests with UI npm run test:ui ``` ## For Claude Desktop Users Based on the [official MCP quickstart guide](https://modelcontextprotocol.io/quickstart/server), Claude Desktop integration follows these steps: ### Setup Steps 1. **Complete the basic setup** (steps 1-4 from development setup above): ```bash git clone <repository-url> cd basecamp-mcp-server npm install npm run setup # Configure .env file with OAuth credentials npm run auth ``` 2. **Generate Claude Desktop configuration:** ```bash npm run config:claude ``` 3. **Restart Claude Desktop completely** (quit and reopen the application) 4. **Verify in Claude Desktop:** - Look for the "Search and tools" icon (🔍) in the chat interface - You should see "basecamp" listed with all 46 tools available - Toggle the tools on to enable Basecamp integration ### Claude Desktop Configuration The configuration is automatically created at: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `~/AppData/Roaming/Claude/claude_desktop_config.json` - **Linux**: `~/.config/claude-desktop/claude_desktop_config.json` Example configuration generated: ```json { "mcpServers": { "basecamp": { "command": "node", "args": ["/path/to/your/project/dist/index.js"], "env": { "BASECAMP_ACCOUNT_ID": "your_account_id" } } } } ``` ### Usage in Claude Desktop Ask Claude things like: - "What are my current Basecamp projects?" - "Show me the latest campfire messages from the Technology project" - "Create a new card in the Development column with title 'Fix login bug'" - "Get all todo items from the Marketing project" - "Search for messages containing 'deadline'" ### Troubleshooting Claude Desktop **Check Claude Desktop logs** (following [official debugging guide](https://modelcontextprotocol.io/quickstart/server#troubleshooting)): ```bash # macOS/Linux - Monitor logs in real-time tail -n 20 -f ~/Library/Logs/Claude/mcp*.log # Check for specific errors ls ~/Library/Logs/Claude/mcp-server-basecamp.log ``` **Common issues:** - **Tools not appearing**: Verify configuration file syntax and restart Claude Desktop - **Connection failures**: Check that Node.js path and script path are absolute paths - **Authentication errors**: Ensure OAuth flow completed successfully (`oauth_tokens.json` exists) ## Available MCP Tools Once configured, you can use these tools in Cursor: - `get_projects` - Get all Basecamp projects - `get_project` - Get details for a specific project - `get_todolists` - Get todo lists for a project - `get_todos` - Get todos from a todo list - `search_basecamp` - Search across projects, todos, and messages - `get_comments` - Get comments for a Basecamp item - `get_campfire_lines` - Get recent messages from a Basecamp campfire - `get_daily_check_ins` - Get project's daily check-in questions - `get_question_answers` - Get answers to daily check-in questions - `create_attachment` - Upload a file as an attachment - `get_events` - Get events for a recording - `get_webhooks` - List webhooks for a project - `create_webhook` - Create a webhook - `delete_webhook` - Delete a webhook - `get_documents` - List documents in a vault - `get_document` - Get a single document - `create_document` - Create a document - `update_document` - Update a document - `trash_document` - Move a document to trash ### Card Table Tools - `get_card_table` - Get the card table details for a project - `get_columns` - Get all columns in a card table - `get_column` - Get details for a specific column - `create_column` - Create a new column in a card table - `update_column` - Update a column title - `move_column` - Move a column to a new position - `update_column_color` - Update a column color - `put_column_on_hold` - Put a column on hold (freeze work) - `remove_column_hold` - Remove hold from a column (unfreeze work) - `watch_column` - Subscribe to notifications for changes in a column - `unwatch_column` - Unsubscribe from notifications for a column - `get_cards` - Get all cards in a column - `get_card` - Get details for a specific card - `create_card` - Create a new card in a column - `update_card` - Update a card - `move_card` - Move a card to a new column - `complete_card` - Mark a card as complete - `uncomplete_card` - Mark a card as incomplete - `get_card_steps` - Get all steps (sub-tasks) for a card - `create_card_step` - Create a new step (sub-task) for a card - `get_card_step` - Get details for a specific card step - `update_card_step` - Update a card step - `delete_card_step` - Delete a card step - `complete_card_step` - Mark a card step as complete - `uncomplete_card_step` - Mark a card step as incomplete ### Example Cursor Usage Ask Cursor things like: - "Show me all my Basecamp projects" - "What todos are in project X?" - "Search for messages containing 'deadline'" - "Get details for the Technology project" - "Show me the card table for project X" - "Create a new card in the 'In Progress' column" - "Move this card to the 'Done' column" - "Update the color of the 'Urgent' column to red" - "Mark card as complete" - "Show me all steps for this card" - "Create a sub-task for this card" - "Mark this card step as complete" ## Architecture The project uses the **official @modelcontextprotocol/sdk** for maximum reliability and compatibility: 1. **MCP Server** (`src/index.ts`) - Official MCP SDK with 46 tools, compatible with both Cursor and Claude Desktop 2. **OAuth App** (`src/lib/oauth-app.ts`) - Handles OAuth 2.0 flow with Basecamp 3. **Token Storage** (`src/lib/token-storage.ts`) - Securely stores OAuth tokens 4. **Basecamp Client** (`src/lib/basecamp-client.ts`) - Basecamp API client library 5. **Type Definitions** (`src/types/basecamp.ts`) - Complete TypeScript interfaces 6. **Configuration Scripts**: - NPM scripts for setup, authentication, and config generation - Built-in TypeScript compilation and testing ## Troubleshooting ### Common Issues (Both Clients) - 🔴 **Red/Yellow indicator:** Run `npm run setup` to build the project and dependencies - 🔴 **"0 tools available":** Project not built or dependencies missing - run setup script - 🔴 **"Tool not found" errors:** Restart your client (Cursor/Claude Desktop) completely - ⚠️ **Missing BASECAMP_ACCOUNT_ID:** Add to `.env` file, then re-run the config generator ### Quick Fixes **Problem: Server won't start** ```bash # Test if MCP server works: node dist/index.js # If this fails, run: npm run build ``` **Problem: Wrong Node.js version** ```bash node --version # Must be 18+ # If too old, install newer Node.js and re-run setup ``` **Problem: Authentication fails** ```bash # Check OAuth flow: npm run auth # Visit http://localhost:8000 and complete login ``` ### Manual Configuration (Last Resort) **Cursor config location:** `~/.cursor/mcp.json` (macOS/Linux) or `%APPDATA%\Cursor\mcp.json` (Windows) **Claude Desktop config location:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ```json { "mcpServers": { "basecamp": { "command": "node", "args": ["/full/path/to/your/project/dist/index.js"], "cwd": "/full/path/to/your/project", "env": { "BASECAMP_ACCOUNT_ID": "your_account_id" } } } } ``` ## Finding Your Account ID If you don't know your Basecamp account ID: 1. Log into Basecamp in your browser 2. Look at the URL - it will be like `https://3.basecamp.com/4389629/projects` 3. The number (4389629 in this example) is your account ID ## Security Notes - Keep your `.env` file secure and never commit it to version control - The OAuth tokens are stored locally in `oauth_tokens.json` - This setup is designed for local development use ## Acknowledgments This TypeScript implementation was inspired by and built upon the excellent foundation provided by the original **Python [Basecamp MCP Server](https://github.com/georgeantonopoulos/Basecamp-MCP-Server)**. **Thank you** to the original Python project maintainers for creating a solid foundation that enabled this TypeScript adaptation! 🙏 ## License This project is licensed under the MIT License.