Content
# 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.
