Skip to main content
Glama
Basecamp MCP Server

Basecamp MCP Server

by jhliberty

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

# 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

Related MCP server: Basecamp MCP Server

Local Development Setup

For Development

  1. Clone and build the project:

    git clone <repository-url>
    cd basecamp-mcp-server
    npm install
    npm run build
  2. Run setup script:

    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:

    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:

    npm run auth

    Visit http://localhost:8000 and complete the OAuth flow.

  5. Generate configurations:

    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

# 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, Claude Desktop integration follows these steps:

Setup Steps

  1. 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 auth
  2. Generate Claude Desktop configuration:

    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:

{
  "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.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

# Test if MCP server works:
node dist/index.js
# If this fails, run: npm run build

Problem: Wrong Node.js version

node --version  # Must be 18+
# If too old, install newer Node.js and re-run setup

Problem: Authentication fails

# 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)

{
    "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.

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 tools
complete_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).

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

    B3/5.0

    Scored across 33 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

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

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -