Basecamp

This MCP server exposes Basecamp tools to AI assistants and code environments, enabling you to access projects, to‑dos, messages, and creation of new tasks through a single, scriptable interface. It streamlines how you ask your tools to fetch and update Basecamp data, making it easy to integrate Basecamp workflows into your AI-assisted development and project management.

How to use

Run the MCP server locally and connect your MCP client or editor to the stdio endpoint. You will start the server, then enable the basecamp tools in your AI assistant or chat environment. Once connected, you can retrieve project information, explore to‑do sets and lists, read messages with optional rendered formats, and create new to‑dos directly from natural language requests or structured calls. The server exposes core capabilities for working with projects, to‑dos, messages, and task creation so you can automate common Basecamp workflows.

How to install

Prerequisites: you need Node.js installed on your machine. You also need a package manager such as npm. Install dependencies and build the MCP server, then run the entrypoint that starts the stdio server.

Steps you should follow directly in your project directory:

# 1) Install dependencies
npm install

# 2) Build
npm run build

# 3) Start the MCP server (stdio)
node build/basecamp-mcp.js

Additional notes

Configure the client to connect via a stdio MCP server. In your editor or IDE, point the MCP client to the stdio entry and provide the path to any needed environment file. A typical setup uses a .env file at the project root for sensitive values. Do not commit the .env file to version control.

Configuration example for the client (stdio) in your editor supports starting the server with the command and using the environment file that holds required values.

Troubleshooting tips include verifying Node.js ES module compatibility, handling API token or rate limits, and ensuring the requested Basecamp features exist in your workspace (some projects may not enable certain tools in their setup).

Security and notes

Keep your environment file secure and avoid committing it. When running locally, ensure your development environment restricts access to the MCP server to trusted clients. If you encounter authentication or rate limiting, review your tokens and adjust request frequency as needed.

Troubleshooting (quick)

ESM import errors may occur if your project is not configured for NodeNext. Ensure the project uses a standard TS/Node setup for ES module imports.

HTTP 401/429 errors typically indicate token issues or excessive request volume. Validate tokens and reduce request frequency; the client will retry once on 429 based on Retry-After guidance.

If you do not see a to‑do set or a message board, the target project may not have those tools enabled in its dock.

Available tools

list_projects

Lists projects with rich metadata such as status, timestamps, purpose, client flags, bookmarks, and enabled dock tools; supports pagination via the nextPage link.

get_todoset

Resolves and returns a project’s to‑do set from the dock; includes the to‑do set URL and optional lists.

list_todolists

Lists to‑do lists for a project’s to‑do set, enabling you to browse tasks within that project.

list_messages

Lists messages on the project Message Board with optional full content rendering (markdown/html/text) and pagination.

get_message

Fetches a single message, with rendered content or raw JSON depending on the request.

create_todo

Creates a to‑do in a specified list with a title, optional description, and an optional due date.