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" }

or

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.