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 .env file 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.

License

ISC

Acknowledgments

• @modelcontextprotocol/sdk

• Basecamp API