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