Skip to main content
Glama
Basecamp MCP Server

Basecamp MCP Server

by vapvarun

Basecamp MCP Server

License: GPL v2 Node.js Version TypeScript MCP

A Model Context Protocol (MCP) server for complete Basecamp automation. This server allows AI assistants like Claude to interact with Basecamp projects, cards, todos, comments, and more.

Author: Varun Dubey (vapvarun) | Company: Wbcom Designs

⚠️ Important: Setup Required

If you cloned this from GitHub, you need to create your config.json file:

# 1. Copy the example config
cp config.example.json config.json

# 2. Edit config.json and add your Basecamp credentials
# (See "Getting Basecamp Credentials" section below)

Note: config.json is gitignored and will never be committed to keep your credentials safe.

Related MCP server: Basecamp 2 MCP

Features

✅ Complete Basecamp API Coverage

  • Read and comment on cards/todos

  • Create, update, move, and trash cards

  • Manage projects, columns, and steps

  • Handle todos and checklists

  • List and manage people

  • Track events and activity

✅ 40+ MCP Tools Available

  • Complete Basecamp API integration via MCP tools

  • Full CRUD operations for all Basecamp resources

  • Search and utility functions

✅ Smart Features

  • Auto-detect account ID

  • Extract images from comments

  • Parse Basecamp URLs

  • Fuzzy project search

Installation

1. Install Dependencies

cd basecamp-mcp-server
npm install

2. Build the Server

npm run build

3. Configure Basecamp Authentication

You have two options:

export BASECAMP_ACCESS_TOKEN="your_access_token_here"
export BASECAMP_ACCOUNT_ID="your_account_id"  # Optional, will auto-detect

Option B: Config File

Create a config.json file in the project root:

{
  "accessToken": "your_access_token_here",
  "accountId": "your_account_id"
}

Note: Use config.example.json as a template. Never commit config.json to version control.

Getting Basecamp Credentials

Step 1: Create a Basecamp App

  1. Go to Basecamp Integrations

  2. Click "Register a new app"

  3. Fill in the details:

    • Name: Your app name (e.g., "My MCP Server")

    • Company: Your company/name

    • Website: Your website URL

    • Redirect URI: http://localhost:3000/callback (or your callback URL)

Step 2: Get OAuth Credentials

From your app page, note down:

  • Client ID

  • Client Secret

Step 3: Get an access token

Use the ready-made bootstrap in oauth/. Summary:

  1. cp oauth/oauth-app.example.json oauth/oauth-app.json and fill in the client_id, client_secret, and redirect_uri from step 2.

  2. Symlink oauth/helper.php + oauth/oauth-app.json into a local WordPress site's wp-content/mu-plugins/.

  3. Visit that site's admin → Basecamp OAuth → Connect to Basecamp.

  4. Paste the displayed tokens into config.json.

  5. Remove the mu-plugin link. The helper is only needed once.

Automatic refresh (recommended). If you also provide BASECAMP_REFRESH_TOKEN, BASECAMP_CLIENT_ID, and BASECAMP_CLIENT_SECRET (env or config.json), the server keeps the access_token fresh itself - proactively, shortly before it expires, and reactively on a 401 - caching the result in .basecamp-token-cache.json. No cron and no "restart Claude Desktop" step needed.

The legacy oauth/refresh-token.sh / refresh-token.cjs / sync-token.sh scripts are now optional (handy for first-time setup or manual recovery) and are no longer required once the refresh credentials are configured. Walkthrough in oauth/README.md.

Using with Claude Desktop

1. Add to Claude Desktop Config

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server:

{
  "mcpServers": {
    "basecamp": {
      "command": "node",
      "args": ["/absolute/path/to/basecamp-mcp-server/build/index.js"],
      "env": {
        "BASECAMP_ACCESS_TOKEN": "your_access_token_here",
        "BASECAMP_ACCOUNT_ID": "your_account_id",
        "BASECAMP_REFRESH_TOKEN": "your_refresh_token",
        "BASECAMP_CLIENT_ID": "your_oauth_client_id",
        "BASECAMP_CLIENT_SECRET": "your_oauth_client_secret"
      }
    }
  }
}

2. Restart Claude Desktop

The Basecamp tools will now be available in Claude.

Available Tools

Reading & Commenting

  • basecamp_read - Read card/todo with comments and images

  • basecamp_comment - Post a comment to any card/todo

Project Management

  • basecamp_list_projects - List all projects

  • basecamp_get_project - Get project details

  • basecamp_create_project - Create a new project

  • basecamp_update_project - Update project

  • basecamp_trash_project - Delete project

Card Operations

  • basecamp_list_columns - List columns in a card table

  • basecamp_list_cards - List cards in a column. Auto-paginates by default — walks every page via Basecamp's Link header so a column with 200+ cards arrives in one array. Pass {single_page: true, page: N} for the old page-by-page behaviour.

  • basecamp_list_card_ids - Compact card listing for iteration. Returns only id / title / status / app_url / timestamps / comment count / assignees / completed flag — payload ~5% of list_cards. Right tool when you just need to walk IDs (e.g. loop over a Done column and feed each id to get_card or list_comments). Always auto-paginates.

  • basecamp_get_card - Get card details

  • basecamp_create_card - Create a new card

  • basecamp_update_card - Update card details

  • basecamp_move_card - Move card to different column

  • basecamp_trash_card - Delete card

Card Steps (Checklists)

  • basecamp_list_steps - List steps on a card

  • basecamp_add_step - Add a new step

  • basecamp_complete_step - Mark step as done

  • basecamp_uncomplete_step - Mark step as not done

Todos

  • basecamp_get_todo - Get todo details

  • basecamp_create_todo - Create a new todo

  • basecamp_complete_todo - Complete todo

  • basecamp_uncomplete_todo - Uncomplete todo

People

  • basecamp_list_people - List all people

  • basecamp_get_person - Get person details

Events & Activity

  • basecamp_get_events - Get recent activity

Search & Utility

  • basecamp_find_project - Search projects by name

  • basecamp_parse_url - Parse Basecamp URL to extract IDs

Usage Examples

Example 1: Read a Card with Comments

// In Claude Desktop, you can simply ask:
// "Read this Basecamp card: https://3.basecamp.com/5798509/buckets/37594834/card_tables/cards/9010883489"

// The tool will be called automatically:
{
  "tool": "basecamp_read",
  "arguments": {
    "url": "https://3.basecamp.com/5798509/buckets/37594834/card_tables/cards/9010883489",
    "include_comments": true,
    "include_images": true
  }
}

Example 2: Create a Card

// "Create a card in project 37594834, column 7389123 titled 'New Feature' with description 'Implement OAuth'"

{
  "tool": "basecamp_create_card",
  "arguments": {
    "project_id": "37594834",
    "column_id": "7389123",
    "title": "New Feature",
    "content": "Implement OAuth authentication",
    "due_on": "2024-12-31"
  }
}

Example 3: Move Card to Different Column

// "Move card 9010883489 to the Done column (column 7389456)"

{
  "tool": "basecamp_move_card",
  "arguments": {
    "project_id": "37594834",
    "card_id": "9010883489",
    "to_column": "7389456"
  }
}

Example 4: Post a Comment

// "Post a comment to this card saying 'Work completed!'"

{
  "tool": "basecamp_comment",
  "arguments": {
    "url": "https://3.basecamp.com/5798509/buckets/37594834/card_tables/cards/9010883489",
    "comment": "Work completed! ✅"
  }
}

Development

Run in Development Mode

npm run dev  # Watch mode - rebuilds on changes

Test the Server

# Build first
npm run build

# Run directly
node build/index.js

# Or with explicit config
BASECAMP_ACCESS_TOKEN="your_token" node build/index.js

Debug with MCP Inspector

npx @modelcontextprotocol/inspector node build/index.js

Project Structure

basecamp-mcp-server/
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # Main MCP server implementation
│   ├── basecamp-api.ts    # Basecamp API client
│   ├── tools.ts           # MCP tool definitions
│   └── config.ts          # Configuration loader
├── build/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── config.example.json    # Example config
└── README.md

Architecture

Key Components

  1. BasecampAPI (basecamp-api.ts)

    • Complete Basecamp API v3 client

    • Handles OAuth and all API endpoints

    • Full TypeScript implementation

  2. BasecampMCPServer (server.ts)

    • Implements MCP protocol

    • Routes tool calls to API methods

    • Handles responses and errors

  3. Tools (tools.ts)

    • Defines all available MCP tools

    • Includes input schemas and descriptions

  4. Config (config.ts)

    • Loads credentials from env or file

    • Handles configuration management

Troubleshooting

"Basecamp credentials not found"

Make sure you've set either:

  • Environment variables (BASECAMP_ACCESS_TOKEN)

  • Or created a config.json file

"Failed to refresh expired token"

Your access token has expired. Get a new one via OAuth or use a refresh token.

"Invalid Basecamp URL"

Make sure the URL format is correct:

  • Cards: https://3.basecamp.com/{account}/buckets/{project}/card_tables/cards/{card_id}

  • Todos: https://3.basecamp.com/{account}/buckets/{project}/todos/{todo_id}

Tools not appearing in Claude

  1. Check Claude Desktop config file path is correct

  2. Ensure the command path points to build/index.js

  3. Restart Claude Desktop completely

  4. Check Claude Desktop logs for errors

"Failed to fetch projects" / 400 Bad Request / runaway requests

If basecamp_list_projects / basecamp_find_project return empty or "Failed to fetch projects", you are almost certainly running a stale build. Run git pull && npm run build and restart the MCP server so the new build/ loads (a rebuild alone does not restart the already-spawned stdio process).

This symptom came from two Basecamp API-contract violations that are now fixed in the client — keep them in mind if you touch getProjects/getAll:

  1. Never send status=active on /projects.json. Basecamp only accepts status=archived or status=trashed; active is the default and is rejected as an invalid value (400 Bad Request). To list active projects, omit the status parameter entirely.

  2. Never hand-build page=N numbers. Follow the RFC 5988 Link header (rel="next") until it's absent, and stop on any non-2xx response. Manually incrementing page against a perpetually-400ing endpoint produces tens of thousands of failed requests (we observed page=55940) and gets the source IP blocked by Basecamp. getAll() enforces this (Link-header walk, stops on 4xx/5xx, maxPages cap).

If your IP was blocked during such a runaway, deploy the fixed build and contact Basecamp support to request an unblock.

API Reference

Full Basecamp API documentation: https://github.com/basecamp/bc3-api

Contributing

Contributions are welcome! To contribute:

  1. Fork the repository

  2. Make changes in the appropriate files

  3. Build: npm run build

  4. Test with MCP Inspector

  5. Submit a pull request

For detailed guidelines, see CONTRIBUTING.md

License

GPL v2 or later

Credits & Author

Created by: Varun Dubey (vapvarun) Company: Wbcom Designs Email: varun@wbcomdesigns.com

Acknowledgments

Support

For issues related to:

Professional Support

For professional support, custom development, or enterprise solutions:


Made with ❤️ by Varun Dubey at Wbcom Designs

Available Tools

88 tools
basecamp_activate_recordingB

Reactivate a trashed or archived Basecamp recording

Inputs: project_id (required), recording_id (required).

basecamp_add_stepB

Add a new step to a card

Inputs: title (required), card_id (required), project_id (required), due_on, +1 more.

basecamp_archive_recordingC

Archive any Basecamp recording

Inputs: project_id (required), recording_id (required).

basecamp_change_column_colorB

Change the color of a card table column. Available colors: white, red, orange, yellow, green, blue, aqua, purple, gray, pink, brown

Inputs: color (required), column_id (required), project_id (required).

basecamp_commentB

Post a comment to any Basecamp card or todo. Can include attachments by providing attachment_sgids.

Inputs: url (required), comment (required), attachment_sgids.

basecamp_comment_with_fileA

Post a comment with an attached file (image, video, document) to any Basecamp card or todo. Automatically uploads the file and embeds it in one step.

Inputs: url (required), comment (required), file_path (required), caption.

basecamp_complete_stepC

Mark a step as completed

Inputs: step_id (required), project_id (required).

basecamp_complete_todoB

Mark a to-do as completed

Inputs: todo_id (required), project_id (required).

basecamp_create_campfire_lineA

Post a new message to a Campfire chat. Can include images and videos.

Inputs: content (required), project_id (required), campfire_id (required), attachment_sgids.

basecamp_create_cardA

Create a new card in a specific column. Can include attachments by providing attachment_sgids.

Inputs: title (required), column_id (required), project_id (required), due_on, +3 more.

basecamp_create_columnC

Create a new column in a card table

Inputs: title (required), project_id (required), card_table_id (required), description.

basecamp_create_documentB

Create a new document in the vault

Inputs: title (required), content (required), vault_id (required), project_id (required).

basecamp_create_messageA

Post a new message/announcement to the message board. Can include images and videos.

Inputs: content (required), subject (required), project_id (required), message_board_id (required), +1 more.

basecamp_create_projectC

Create a new Basecamp project

Inputs: name (required), description.

basecamp_create_schedule_entryB

Create a new calendar event in the schedule

Inputs: summary (required), starts_at (required), project_id (required), schedule_id (required), +5 more.

basecamp_create_todoB

Create a new to-do in a to-do list

Inputs: content (required), project_id (required), todolist_id (required), due_on, +4 more.

basecamp_create_todolistB

Create a new to-do list in a project

Inputs: name (required), project_id (required), todoset_id (required), description.

basecamp_create_uploadA

Create a file upload in a vault. First use basecamp_upload_attachment to get an attachable_sgid, then use this to place it in a vault.

Inputs: vault_id (required), project_id (required), attachable_sgid (required), base_name, +1 more.

basecamp_create_vaultB

Create a new sub-vault (folder) within a vault

Inputs: title (required), project_id (required), parent_vault_id (required).

basecamp_delete_campfire_lineB

Delete a chat message/line from a Campfire

Inputs: line_id (required), project_id (required), campfire_id (required).

basecamp_find_projectA

Find a project by name using fuzzy matching

Inputs: search_term (required).

basecamp_get_campfireA

Get details of a specific Campfire chat

Inputs: project_id (required), campfire_id (required).

basecamp_get_cardB

Get detailed information about a specific card

Inputs: card_id (required), project_id (required).

basecamp_get_columnA

Get detailed information about a specific column (including subscribers, color, cards count)

Inputs: column_id (required), project_id (required).

basecamp_get_documentB

Get a specific document with full content

Inputs: project_id (required), document_id (required).

basecamp_get_eventsA

Get recent activity/events for the account or a specific project

Inputs: limit, project_id.

basecamp_get_messageB

Get a specific message with full content

Inputs: message_id (required), project_id (required).

basecamp_get_personC

Get details about a specific person

Inputs: person_id (required).

basecamp_get_projectB

Get detailed information about a specific project

Inputs: project_id (required).

basecamp_get_project_dockA

Get a clean map of all dock tool IDs for a project (message_board, todoset, vault, chat, schedule, questionnaire, inbox, kanban_board). Use this to quickly find tool IDs needed by other endpoints.

Inputs: project_id (required).

basecamp_get_schedule_entryC

Get a specific schedule entry/event

Inputs: entry_id (required), project_id (required).

basecamp_get_todoB

Get details of a specific to-do

Inputs: todo_id (required), project_id (required).

basecamp_get_todolistB

Get details of a specific to-do list

Inputs: project_id (required), todolist_id (required).

basecamp_get_todosetA

Get the To-do Set for a project (contains all todo lists)

Inputs: project_id (required).

basecamp_get_uploadB

Get details of a specific file upload

Inputs: upload_id (required), project_id (required).

basecamp_get_vaultA

Get details of a specific vault (folder)

Inputs: vault_id (required), project_id (required).

basecamp_index_buildA

Build full index of all projects, card tables, and columns for fast lookups

Inputs: no named parameters.

basecamp_index_find_columnA

Find a column by name within a project (fast lookup)

Inputs: project_id (required), column_name (required).

basecamp_index_get_columnsB

Get all columns for a project from index

Inputs: project_id (required).

basecamp_index_get_projectC

Get project details from index (project ID, card tables, columns)

Inputs: project_id (required).

basecamp_index_statsA

Get index statistics (total projects, columns, last update time)

Inputs: no named parameters.

basecamp_index_update_projectC

Update index for a specific project

Inputs: project_id (required).

basecamp_list_campfire_linesB

List chat messages/lines in a Campfire

Inputs: project_id (required), campfire_id (required).

basecamp_list_campfiresA

List all Campfires (group chats) visible to the current user

Inputs: no named parameters.

basecamp_list_card_idsA

Compact card listing for iteration — returns only id, title, status, app_url, timestamps, comment count, assignee names, and completed flag for every card in a column. Payload is ~5% of list_cards so this is the right tool when you just need to walk IDs (e.g. to feed basecamp_get_card in a loop over the Done column). Always auto-paginates.

Inputs: column_id (required), project_id (required).

basecamp_list_cardsA

List cards in a column. Defaults to auto-paginating — walks every page via Link headers so a 224-card Done column returns as one array instead of the first 15 rows. Pass {single_page: true, page: N} to restrict to a single page (useful for UI-style pagination).

Inputs: column_id (required), project_id (required), page, single_page.

basecamp_list_columnsB

List all columns in a card table

Inputs: table_id (required), project_id (required).

basecamp_list_documentsB

List all documents in a vault (Docs & Files)

Inputs: vault_id (required), project_id (required).

basecamp_list_messagesB

List all messages in a message board

Inputs: project_id (required), message_board_id (required).

basecamp_list_peopleB

List all people in the organization

Inputs: project_id.

basecamp_list_pingable_peopleA

List all people who can be pinged (mentioned) on this Basecamp account

Inputs: no named parameters.

basecamp_list_projectsB

List all Basecamp projects

Inputs: status.

basecamp_list_schedule_entriesB

List all schedule entries (calendar events) in a project

Inputs: project_id (required), schedule_id (required), status, end_date, +1 more.

basecamp_list_stepsB

List all steps/checklist items on a card

Inputs: card_id (required), project_id (required).

basecamp_list_todolistsB

List all to-do lists in a project

Inputs: project_id (required), todoset_id (required), status.

basecamp_list_todosA

List all to-dos in a to-do list

Inputs: project_id (required), todolist_id (required), status, completed.

basecamp_list_uploadsB

List all file uploads in a vault

Inputs: vault_id (required), project_id (required).

basecamp_list_vaultsB

List all sub-vaults (folders) within a vault

Inputs: vault_id (required), project_id (required).

basecamp_manage_project_peopleC

Grant or revoke project access for people

Inputs: project_id (required), grant, revoke.

basecamp_move_cardC

Move a card to a different column (status change)

Inputs: card_id (required), to_column (required), project_id (required), position.

basecamp_move_columnB

Move/reorder a column within a card table

Inputs: source_id (required), target_id (required), project_id (required), card_table_id (required), +1 more.

basecamp_parse_urlC

Parse a Basecamp URL to extract IDs (account, project, card/todo)

Inputs: url (required).

basecamp_pin_messageB

Pin a message to the top of the message board

Inputs: message_id (required), project_id (required).

basecamp_readB

Read a Basecamp card or todo with optional comments and images. Supports any Basecamp URL.

Inputs: url (required), include_images, include_comments.

basecamp_remove_column_on_holdC

Remove the on-hold section from a column

Inputs: column_id (required), project_id (required).

basecamp_reposition_stepB

Change the position of a step within a card

Inputs: card_id (required), step_id (required), position (required), project_id (required).

basecamp_set_column_on_holdC

Add an on-hold section to a column

Inputs: column_id (required), project_id (required).

basecamp_trash_cardC

Move a card to trash

Inputs: card_id (required), project_id (required).

basecamp_trash_projectB

Move a project to trash

Inputs: project_id (required).

basecamp_trash_recordingA

Trash any Basecamp recording (card, todo, message, document, etc.)

Inputs: project_id (required), recording_id (required).

basecamp_uncomplete_stepB

Mark a step as incomplete

Inputs: step_id (required), project_id (required).

basecamp_uncomplete_todoA

Mark a to-do as incomplete

Inputs: todo_id (required), project_id (required).

basecamp_unpin_messageC

Unpin a message from the message board

Inputs: message_id (required), project_id (required).

basecamp_unwatch_columnB

Stop watching/subscribing to a column

Inputs: column_id (required), project_id (required).

basecamp_update_cardB

Update an existing card (title, content, assignees, due date, completion). Can include attachments.

Inputs: card_id (required), project_id (required), title, due_on, +4 more.

basecamp_update_columnC

Update a column title or description

Inputs: column_id (required), project_id (required), title, description.

basecamp_update_documentC

Update an existing document

Inputs: project_id (required), document_id (required), title, content.

basecamp_update_messageC

Update an existing message

Inputs: message_id (required), project_id (required), content, subject.

basecamp_update_projectB

Update a project name, description, access policy, or schedule dates

Inputs: project_id (required), name, end_date, admissions, +2 more.

basecamp_update_schedule_entryC

Update a schedule entry/event

Inputs: entry_id (required), project_id (required), all_day, ends_at, +4 more.

basecamp_update_stepA

Update a step title, due date, or assignees

Inputs: step_id (required), project_id (required), title, due_on, +1 more.

basecamp_update_todoD

Update a to-do

Inputs: todo_id (required), project_id (required), due_on, content, +3 more.

basecamp_update_todolistC

Update a to-do list

Inputs: project_id (required), todolist_id (required), name, description.

basecamp_update_uploadB

Update a file upload description or name

Inputs: upload_id (required), project_id (required), base_name, description.

basecamp_update_vaultC

Rename a vault (folder)

Inputs: title (required), vault_id (required), project_id (required).

basecamp_upload_attachmentA

Upload a file (image, video, document) to Basecamp. Returns an attachable_sgid that can be used in comments, messages, or any rich text content.

Inputs: file_path (required), caption, file_name.

basecamp_watch_columnB

Start watching/subscribing to a column for notifications

Inputs: column_id (required), project_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.5/5.0

    Scored across 88 tools

    Disambiguation2/5

    Several tools have overlapping purposes, such as basecamp_read vs. basecamp_get_card/basecamp_get_todo, basecamp_comment vs. basecamp_comment_with_file, and basecamp_trash_recording vs. basecamp_trash_card/basecamp_trash_project. Agents may struggle to choose the correct tool without deep domain knowledge.

    Naming Consistency4/5

    Most tools follow the predictable pattern basecamp_<verb>_<noun> (e.g., list_projects, create_card, update_todo). Minor deviations include basecamp_comment, basecamp_read, basecamp_comment_with_file, and the index_* group, which uses a slightly different prefix style.

    Tool Count1/5

    With 88 tools, the server is extremely bloated. Many tools are redundant or overly granular (e.g., list_cards vs. list_card_ids, multiple index helpers). The count far exceeds what is needed for a coherent MCP server, likely overwhelming agents.

    Completeness4/5

    The tool surface covers almost all major Basecamp resources: projects, card tables, todos, messages, vaults, documents, uploads, schedule, campfires, and people. Minor gaps exist, such as no direct campfire line update or message deletion, but generic trash/archive/activate tools partially fill these.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers