Basecamp MCP Server
Provides comprehensive integration with Basecamp 3, offering 46 tools for managing projects, todo lists, campfire messages, card tables, documents, webhooks, and daily check-ins. Supports full CRUD operations for cards, columns, and card steps, along with search functionality across projects and messages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Basecamp MCP Server show me my active todos in the Marketing project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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)
# 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 IDEPrerequisites
Node.js 18+ (required for ES modules)
A Basecamp 3 account
A Basecamp OAuth application (create one at https://launchpad.37signals.com/integrations)
Related MCP server: Basecamp MCP Server
Local Development Setup
For Development
Clone and build the project:
git clone <repository-url> cd basecamp-mcp-server npm install npm run buildRun setup script:
npm run setupThe setup script automatically:
✅ Installs all TypeScript dependencies
✅ Builds the project to
dist/✅ Creates
.envtemplate file✅ Tests MCP server functionality
Configure OAuth credentials: Edit the generated
.envfile: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)"Authenticate with Basecamp:
npm run authVisit http://localhost:8000 and complete the OAuth flow.
Generate configurations:
npm run config:cursor # For Cursor IDE npm run config:claude # For Claude DesktopRestart your AI assistant completely (quit and reopen)
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
# 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:uiFor Claude Desktop Users
Based on the official MCP quickstart guide, Claude Desktop integration follows these steps:
Setup Steps
Complete the basic setup (steps 1-4 from development setup above):
git clone <repository-url> cd basecamp-mcp-server npm install npm run setup # Configure .env file with OAuth credentials npm run authGenerate Claude Desktop configuration:
npm run config:claudeRestart Claude Desktop completely (quit and reopen the application)
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.jsonWindows:
~/AppData/Roaming/Claude/claude_desktop_config.jsonLinux:
~/.config/claude-desktop/claude_desktop_config.json
Example configuration generated:
{
"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):
# 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.logCommon 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.jsonexists)
Available MCP Tools
Once configured, you can use these tools in Cursor:
get_projects- Get all Basecamp projectsget_project- Get details for a specific projectget_todolists- Get todo lists for a projectget_todos- Get todos from a todo listsearch_basecamp- Search across projects, todos, and messagesget_comments- Get comments for a Basecamp itemget_campfire_lines- Get recent messages from a Basecamp campfireget_daily_check_ins- Get project's daily check-in questionsget_question_answers- Get answers to daily check-in questionscreate_attachment- Upload a file as an attachmentget_events- Get events for a recordingget_webhooks- List webhooks for a projectcreate_webhook- Create a webhookdelete_webhook- Delete a webhookget_documents- List documents in a vaultget_document- Get a single documentcreate_document- Create a documentupdate_document- Update a documenttrash_document- Move a document to trash
Card Table Tools
get_card_table- Get the card table details for a projectget_columns- Get all columns in a card tableget_column- Get details for a specific columncreate_column- Create a new column in a card tableupdate_column- Update a column titlemove_column- Move a column to a new positionupdate_column_color- Update a column colorput_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 columnunwatch_column- Unsubscribe from notifications for a columnget_cards- Get all cards in a columnget_card- Get details for a specific cardcreate_card- Create a new card in a columnupdate_card- Update a cardmove_card- Move a card to a new columncomplete_card- Mark a card as completeuncomplete_card- Mark a card as incompleteget_card_steps- Get all steps (sub-tasks) for a cardcreate_card_step- Create a new step (sub-task) for a cardget_card_step- Get details for a specific card stepupdate_card_step- Update a card stepdelete_card_step- Delete a card stepcomplete_card_step- Mark a card step as completeuncomplete_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:
MCP Server (
src/index.ts) - Official MCP SDK with 46 tools, compatible with both Cursor and Claude DesktopOAuth App (
src/lib/oauth-app.ts) - Handles OAuth 2.0 flow with BasecampToken Storage (
src/lib/token-storage.ts) - Securely stores OAuth tokensBasecamp Client (
src/lib/basecamp-client.ts) - Basecamp API client libraryType Definitions (
src/types/basecamp.ts) - Complete TypeScript interfacesConfiguration 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 setupto 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
.envfile, then re-run the config generator
Quick Fixes
Problem: Server won't start
# Test if MCP server works:
node dist/index.js
# If this fails, run: npm run buildProblem: Wrong Node.js version
node --version # Must be 18+
# If too old, install newer Node.js and re-run setupProblem: Authentication fails
# Check OAuth flow:
npm run auth
# Visit http://localhost:8000 and complete loginManual 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)
{
"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:
Log into Basecamp in your browser
Look at the URL - it will be like
https://3.basecamp.com/4389629/projectsThe number (4389629 in this example) is your account ID
Security Notes
Keep your
.envfile secure and never commit it to version controlThe OAuth tokens are stored locally in
oauth_tokens.jsonThis 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.
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.
Available Tools
33 toolscomplete_cardC
Mark a card as complete
Inputs: card_id (required), project_id (required).
complete_card_stepC
Mark a card step as complete
Inputs: project_id (required), step_id (required).
create_cardC
Create a new card in a column
Inputs: column_id (required), project_id (required), title (required), content, +2 more.
create_card_stepC
Create a new step (sub-task) for a card
Inputs: card_id (required), project_id (required), title (required), assignee_ids, +1 more.
create_columnC
Create a new column in a card table
Inputs: card_table_id (required), project_id (required), title (required).
create_documentC
Create a document in a vault
Inputs: content (required), project_id (required), title (required), vault_id (required).
create_webhookC
Create a webhook
Inputs: payload_url (required), project_id (required), types.
delete_webhookC
Delete a webhook
Inputs: project_id (required), webhook_id (required).
get_campfire_linesB
Get recent messages from a Basecamp campfire (chat room)
Inputs: campfire_id (required), project_id (required).
get_cardC
Get details for a specific card
Inputs: card_id (required), project_id (required).
get_cardsC
Get all cards in a column
Inputs: column_id (required), project_id (required).
get_card_stepsC
Get all steps (sub-tasks) for a card
Inputs: card_id (required), project_id (required).
get_card_tableC
Get the card table details for a project
Inputs: project_id (required).
get_columnsC
Get all columns in a card table
Inputs: card_table_id (required), project_id (required).
get_commentsC
Get comments for a Basecamp item
Inputs: project_id (required), recording_id (required).
get_daily_check_insC
Get project's daily checking questionnaire
Inputs: project_id (required), page.
get_documentsC
List documents in a vault
Inputs: project_id (required), vault_id (required).
get_projectC
Get details for a specific project
Inputs: project_id (required).
get_projectsB
Get all Basecamp projects
Inputs: no named parameters.
get_question_answersC
Get answers on daily check-in question
Inputs: project_id (required), question_id (required), page.
get_todolistsC
Get todo lists for a project
Inputs: project_id (required).
get_todosC
Get todos from a todo list
Inputs: project_id (required), todolist_id (required).
get_uploadsC
List uploads in a project or vault
Inputs: project_id (required), vault_id.
get_webhooksC
List webhooks for a project
Inputs: project_id (required).
global_searchC
Search projects, todos and campfire messages across all projects
Inputs: query (required).
move_cardC
Move a card to a new column
Inputs: card_id (required), column_id (required), project_id (required).
move_columnC
Move a column to a new position
Inputs: card_table_id (required), column_id (required), position (required), project_id (required).
search_basecampC
Search across Basecamp projects, todos, and messages
Inputs: query (required), project_id.
trash_documentC
Move a document to trash
Inputs: document_id (required), project_id (required).
update_cardC
Update a card
Inputs: card_id (required), project_id (required), assignee_ids, content, +2 more.
update_columnC
Update a column title
Inputs: column_id (required), project_id (required), title (required).
update_column_colorC
Update a column color
Inputs: color (required), column_id (required), project_id (required).
update_documentC
Update a document
Inputs: document_id (required), project_id (required), content, title.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Most tools have distinct purposes targeting specific Basecamp resources (e.g., cards, columns, documents, webhooks), but there is some overlap between 'global_search' and 'search_basecamp' which could cause confusion as both appear to handle search functionality across projects. Otherwise, the tool set is well-differentiated.
Tool names follow a highly consistent verb_noun pattern throughout (e.g., create_card, get_cards, update_column). All tools use snake_case with clear, descriptive verbs, making the naming predictable and easy to understand.
With 33 tools, the count is borderline high for a project management server, potentially overwhelming for agents. While Basecamp has many features, this many tools might indicate over-fragmentation (e.g., separate tools for similar operations like get_card and get_cards).
The tool set provides comprehensive coverage for Basecamp's domain, including CRUD operations for cards, columns, documents, webhooks, and search, along with specific features like campfire messages and daily check-ins. No obvious gaps are present; agents can perform full lifecycle management.
Maintenance
Related MCP Connectors
Carbon Voice MCP serves as a bridge that connects AI assistants like ChatGPT, Claude, and Cursor to a user's Carbon Voice account, turning voice messages and conversations into a private, on-demand knowledge base. It provides 28 specialized tools for comprehensive voice messaging management, including creating and sending messages, accessing conversation history with instant transcription, running AI actions (summarization, TLDR generation, meeting notes), and managing workspace collaboration through folders, contacts, and team communications.
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Paymo time tracking, tasks, projects, invoices and transcription in Claude, ChatGPT, Cursor.
Your Aurentia workspace — projects, CRM, tasks, deliverables — in Claude, Cursor or any MCP client.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables MCP-capable clients such as Codex, Cursor, and Claude Desktop to read and manage Basecamp 3 projects through OAuth-authenticated API calls, covering projects, todos, messages, card tables, documents, uploads, and search. It exposes these capabilities as tools for browsing, creating, updating, and organizing Basecamp content via natural language.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP-capable clients such as Codex, Cursor, and Claude Desktop to read and manage Basecamp 3 projects through OAuth-authenticated API calls. Exposes tools covering projects, todos, message boards, campfires, card tables, inbox forwards, documents, uploads, comments, events, webhooks, and search.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP-capable clients such as Codex, Cursor, and Claude Desktop to read and manage Basecamp 3 projects through OAuth-authenticated API calls, covering todolists, todos, messages, campfires, card tables, documents, uploads, comments, and search.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP-capable clients such as Codex, Cursor, and Claude Desktop to read and manage Basecamp 3 projects through OAuth-authenticated API calls. Covers projects, todolists and todos, message boards, campfires, card tables, inbox forwards, documents, uploads, comments, events, webhooks, and search.-