Basecamp MCP Server

How to use

You use this MCP server by configuring an MCP client to connect to the server and by using the defined tools to access Basecamp data. Once connected, you can list projects, read and create messages, manage todos and comments, view people, and interact with kanban boards. Each tool corresponds to a specific Basecamp resource or action, and you can filter results or supply additional details to shape the operation.

How to install

Prerequisites: you need Node.js version 18 or newer installed on your system. You also need a working Basecamp OAuth setup to obtain the client credentials used by the server.

{
  "mcpServers": {
    "basecamp": {
      "command": "npx",
      "args": ["-y", "basecamp-mcp@latest"],
      "env": {
        "BASECAMP_CLIENT_ID": "your_client_id",
        "BASECAMP_CLIENT_SECRET": "your_client_secret",
        "BASECAMP_REFRESH_TOKEN": "your_refresh_token",
        "BASECAMP_USER_AGENT": "YourApp ([email protected])",
        "BASECAMP_ACCOUNT_ID": "account_id"
      }
    }
  }
}

Create a configuration file with the MCP server entry shown above. This config lets the MCP system start the Basecamp MCP server using Node/NPX. After you have the configuration in place, start the server from your project directory using the standard start command used by your environment.

Additional sections

Configuration details, security considerations, and troubleshooting follow in the sections below. You will find the exact environment variables required, a complete configuration example, and a list of all tools exposed by the server. Run the server in a project directory where you can manage environment variables securely and keep sensitive credentials out of version control.

How to start the server

Run the server in development or production mode using the package scripts or commands your project uses. Typical commands are shown in the examples and will start the MCP server so it can accept client connections.

Configuration details

The server requires Basecamp credentials and an account identifier. You must provide the following environment variables in your run environment or within the config snippet you load at startup.

{
  "mcpServers": {
    "basecamp": {
      "command": "npx",
      "args": ["-y", "basecamp-mcp@latest"],
      "env": {
        "BASECAMP_CLIENT_ID": "your_client_id",
        "BASECAMP_CLIENT_SECRET": "your_client_secret",
        "BASECAMP_REFRESH_TOKEN": "your_refresh_token",
        "BASECAMP_USER_AGENT": "YourApp ([email protected])",
        "BASECAMP_ACCOUNT_ID": "account_id"
      }
    }
  }
}

Security and best practices

Treat your OAuth credentials and tokens as secrets. Do not commit them to version control. Use environment-specific configurations and rotate credentials as needed. Limit access to the MCP server to trusted clients and monitor access logs for unusual activity.

Notes and troubleshooting

If you encounter connection issues, verify that the Basecamp credentials are correct and that the Basecamp account ID matches the account you intend to access. Ensure the MCP server is running in the same network as your MCP clients or accessible through your deployment environment. Check that Node.js 18+ is installed and that the startup command is executed from the correct directory.

basecamp_list_projects

List all accessible Basecamp projects with optional filters to refine results.

basecamp_get_project

Fetch detailed information about a specific project, including its dock configuration.

basecamp_list_messages

List messages in a project’s message boards with optional filtering by type or other attributes.

basecamp_list_message_types

List available message types or categories for a project.

basecamp_get_message

Retrieve the details of a single message.

basecamp_create_message

Create a new message with optional category and draft status.

basecamp_update_message

Update a message with advanced content editing (full replace, append, prepend, or search/replace).

basecamp_get_todoset

Retrieve a container that holds all todo lists for a project.

basecamp_list_todos

List todos within a list with status filters (active or archived).

basecamp_create_todo

Create a new todo with an optional description.

basecamp_complete_todo

Mark a todo as complete.

basecamp_uncomplete_todo

Mark a todo as incomplete.

basecamp_list_comments

List comments on any resource across Basecamp.

basecamp_create_comment

Add a comment to any resource.

basecamp_update_comment

Update a comment with advanced content editing (full replace, append, prepend, or search/replace).

basecamp_get_me

Get personal information for the authenticated user.

basecamp_list_people

List people with optional filtering by name, email, or title.

basecamp_get_person

Get details about a specific person.

basecamp_list_kanban_columns

List all kanban columns in a board.

basecamp_list_kanban_cards

List kanban cards in a column with steps and assignees.

basecamp_get_kanban_card

Get complete details of a specific kanban card.

basecamp_create_kanban_card

Create a new kanban card with title, content, and optional checklist steps.

basecamp_update_kanban_card

Update a kanban card with advanced editing and metadata changes.

basecamp_move_kanban_card

Move a kanban card to a different column or position.

basecamp_list_recordings

Browse recent activity across projects with multiple filters for type, date, person, and text search.

basecamp_list_campfire_messages

Browse Campfire chat messages with filtering by campfire, person, text, and date range.