Skip to main content
Glama
jpaoad31

basecamp-mcp

by jpaoad31
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

basecamp-mcp

An MCP server that exposes the basecamp CLI to Claude Desktop (and any other MCP client) over HTTP. It runs as a login-time background service and is reached at a local URL.

It's a thin wrapper: each MCP tool shells out to basecamp <cmd> --json and returns the parsed result. Authentication is handled entirely by the CLI's own token store — this server never sees your password and holds no credentials.

Architecture

Claude Desktop ──HTTP(/mcp)──▶ basecamp-mcp (bun, :7331) ──spawn──▶ basecamp CLI ──▶ Basecamp API
     custom connector           launchd LaunchAgent, runs at login

  • Transport: MCP Streamable HTTP (Web-standard Request/Response via Bun.serve).

  • Bind address: 127.0.0.1 only, with DNS-rebinding protection — not reachable off-box.

  • Lifecycle: a launchd LaunchAgent (RunAtLoad + KeepAlive) starts it at login and restarts it if it dies.

  • Runtime: compiled to a single standalone executable with bun build --compile — Bun is only needed to build, not to run.

Related MCP server: Basecamp MCP Server

Quick start (macOS)

You don't need anything installed first — the setup script handles it all (Homebrew, the basecamp CLI, and Bun).

  1. Open Terminal and paste this, then press Return:

    git clone https://github.com/jpaoad31/basecamp-mcp.git
cd basecamp-mcp
./setup.sh

    It installs the prerequisites, builds the server, sets it to start at login, and opens a browser to log you into Basecamp. If asked for your Mac password, that's Homebrew installing — it's expected.

  2. When it finishes it prints a URL. In Claude Desktop → Settings → Connectors → Add custom connector, paste that URL:

    http://127.0.0.1:7331/mcp

That's it. The server runs automatically every time you log in.

To update later: cd basecamp-mcp && git pull && ./setup.sh.

No git? (zip install)

If someone sent you a zip instead: double-click to unzip, drag the basecamp-mcp folder onto a Terminal window, press Return, then run ./setup.sh.

Prerequisites (manual install)

  • The basecamp CLI installed and on your PATH.

  • Bun (to build).

  • You must log the CLI in once: basecamp auth login.

Install

bun install
./install.sh          # or: bun run install-service

Packaging for someone else

./package.sh          # or: bun run package

Produces basecamp-mcp.zip (source + scripts only). Send it; they run ./setup.sh. The binary is compiled on their machine, which avoids macOS Gatekeeper quarantine.

This builds dist/basecamp-mcp, writes a LaunchAgent to ~/Library/LaunchAgents/com.basecamp.mcp.plist, loads it, and health-checks it.

Then in Claude Desktop → Settings → Connectors → Add custom connector, use:

http://127.0.0.1:7331/mcp

Tools

Tool

What it does

basecamp_auth_status

Report CLI auth status

basecamp_projects_list

List projects (optionally by status)

basecamp_search

Full-text search across all content

basecamp_show

Show any item by ID or URL

basecamp_todos_list

List todos in a project

basecamp_todo_create

Create a todo

basecamp_todo_complete

Complete todo(s)

basecamp_message_post

Post to a message board

basecamp_comment_add

Comment on an item

basecamp_card_create

Create a card in a card table

basecamp_chat_list

List chats/campfires

basecamp_chat_messages

Read recent chat messages

basecamp_chat_post

Post a chat message

basecamp_cli

Escape hatch: run any basecamp command by argv

Development

bun run dev      # watch mode, http://127.0.0.1:7331/mcp
bun run start    # run once
bun run build    # produce dist/basecamp-mcp
curl -s http://127.0.0.1:7331/health   # liveness

Override the port with PORT=… and the CLI location with BASECAMP_BIN=….

Uninstall

./uninstall.sh   # or: bun run uninstall-service

Notes & caveats

  • Security: the basecamp_cli escape hatch can run any CLI command (including destructive ones and auth token). The server is bound to loopback for exactly this reason — anyone who can reach the port acts as you.

  • Claude Desktop connectors: local http:// connector URLs work with recent Desktop builds. If yours refuses a non-HTTPS URL, either update Desktop or fall back to a stdio MCP config pointing at the binary.

  • Logs: ~/Library/Logs/basecamp-mcp.log.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers