Basecamp MCP Server (TypeScript)

A Model Context Protocol (MCP) server that exposes Basecamp tools to AI assistants (e.g., VS Code Chat in Agent mode).
Supports projects, to‑do sets/lists, messages (with rendered content), and creating to‑dos.

Features

Projects
- list_projects — rich listing (status, timestamps, purpose, client flags, bookmarks, enabled dock tools)
- Pagination via HTTP Link header (exposes nextPage)
- Optional raw dock objects
To‑do sets / lists
- Resolves a project’s to‑do set from the project dock
- get_todoset — returns to‑do set id/url; optional lists
- list_todolists — lists to‑do lists for a project’s to‑do set
Messages
- list_messages — resolves the project Message Board from dock, lists messages with pagination
- Optional full content rendering (markdown/html/text)
- get_message — fetch a single message (rendered or raw JSON)
To‑dos
- create_todo — create a to‑do in a list (title, description, optional due_on)

Project layout

src/ ├─ lib/ │ └─ basecamp.ts # Basecamp client (auth refresh, requests, pagination) ├─ tools/ │ ├─ projects.ts # list_projects │ ├─ todosets.ts # get_todoset, list_todolists │ ├─ messages.ts # list_messages, get_message │ └─ todos.ts # create_todo └─ basecamp-mcp.ts # entrypoint (register tools, start stdio server)

Quick start

# 1) Install dependencies npm install # 2) Build npm run build # 3) (Optional) sanity check node build/basecamp-mcp.js # (MCP servers sit and wait on stdio; no output is expected here)

Environment variables

Add your required values in a at the project root.
This file is referenced by the MCP server configuration below.

Do not commit your .env file to version control.

Configure in VS Code (MCP)

Create .vscode/mcp.json in this project:

{ "servers": { "basecamp": { "type": "stdio", "command": "node", "args": ["${workspaceFolder}/build/basecamp-mcp.js"], "envFile": "${workspaceFolder}/.env" } } }

Now restart the server from VS Code:

Command Palette → “MCP: List Servers” → basecamp → Start/Restart
Open Chat, switch to Agent, enable the basecamp tools.

Example tool calls (Agent mode)

Projects (JSON with dock):

Run basecamp.list_projects with { "format": "json", "dock_detail": true, "limit": 5 }

or natural language

retrieve all project information

Resolve to‑do set and lists:

Run basecamp.get_todoset with { "project_id": 123456789 } Run basecamp.list_todolists with { "project_id": 123456789 }

Natural language example

show todo sets and lists for project "{{prpjectName / Id}}"

Create a to‑do:

Run basecamp.create_todo with { "project_id": 123456789, "todolist_id": 222222222, "content": "Kickoff", "due_on": "2025-09-30" }

Natural language example

create a to-do in the "{to do list name}", titled "Update README.md"

Messages (rendered content):

Run basecamp.list_messages with { "project_id": 123456789, "page": 1, "format": "markdown", "include_body": true } Run basecamp.get_message with { "project_id": 123456789, "message_id": 987654321, "render": "markdown" }

get all messages from TestMCP project

get content for this message "{messageId / title"

Pagination: responses include nextPage from the RFC5988 Link header. Call again with { "page": <nextPage> }.

Troubleshooting (quick)

ESM import errors: make sure your project is configured for ESM/NodeNext (standard TS/Node setup).
401/429 from API: verify tokens and reduce request volume; the client retries once on 429 using Retry-After.
No to‑do set / message board: that project may not have those tools enabled in its dock.

License

ISC

Basecamp MCP Server

Basecamp MCP Server (TypeScript)

Features

Project layout

Quick start

Environment variables

Configure in VS Code (MCP)

Example tool calls (Agent mode)

Troubleshooting (quick)

License

Acknowledgments

Tools

New MCP Servers

MCP directory API