hs-basecamp

A read-only MCP server for Basecamp. It gives an MCP client (Claude Code, Cursor, etc.) 8 tools to read one Basecamp account — projects, to-dos, message threads, people, and recent activity. No write operations exist; it cannot modify your Basecamp data.

Internal HyperSense tool. Distributed straight from this GitHub repo — no npm registry involved.

Install

You need Node ≥ 20 and access to the HyperSense-Software/hs-basecamp repo.

# 1. Install the CLI globally (builds from source automatically)
npm install -g github:HyperSense-Software/hs-basecamp

# 2. One-time guided auth (~2 min — see below)
hs-basecamp auth

# 3. Restart your MCP client so it loads the new server

hs-basecamp auth will offer to register the server with Claude Code for you. If you accept, you're done after the restart. Otherwise add the snippet it prints (see MCP client config).

The auth step (register your own OAuth app)

Basecamp's OAuth requires a confidential client_secret, so there's no shared app we can ship — each person authorizes with their own Basecamp login. hs-basecamp auth walks you through it:

1. It opens https://launchpad.37signals.com/integrations.
2. Create an integration. Set the redirect URI to exactly http://localhost:3737/callback.
3. Paste the Client ID and Client Secret back into the prompt.
4. Approve in the browser; the tool captures your token, lets you pick the account, and saves everything locally (0600).

Team tip: an admin can register one integration and share its Client ID + Secret with the team. Each teammate still runs hs-basecamp auth and pastes those shared values — they approve with their own login, so each person gets their own token scoped to their own Basecamp permissions. Nothing shared is a personal secret.

MCP client config

If you didn't let auth add it automatically, register the server manually. The global install puts hs-basecamp on your PATH:

{ "mcpServers": { "basecamp": { "command": "hs-basecamp", "args": [] } } }

Or via the Claude Code CLI:

claude mcp add basecamp --scope user -- hs-basecamp

Tools

Tool	Purpose
list_projects	List active/archived projects
get_project	Project details + dock (tools and ids)
get_recent_activity	Recent items across Message/Todo/Comment/Document
list_todos	To-dos for a project (incomplete by default)
list_messages	Message-board posts
get_message_thread	A message + its comments
list_people	People on a project or the whole account
get_recording	Fetch any object by a URL from a prior result

Updating

npm install -g github:HyperSense-Software/hs-basecamp   # re-run to pull the latest

Your saved auth survives upgrades, so you don't need to re-run hs-basecamp auth. To pin a specific version, append #v0.2.0 (any tag/branch/commit).

Configuration & secrets

hs-basecamp auth writes a config file at:

• macOS/Linux: ~/.config/hs-basecamp/config.json (or $XDG_CONFIG_HOME/hs-basecamp/)
• Windows: %APPDATA%/hs-basecamp/config.json

…with 0600 permissions, holding accountId, userAgent, clientId, clientSecret, refreshToken. Secrets never leave your machine except in requests to Basecamp.

Env override (CI / advanced): any of BASECAMP_ACCOUNT_ID, BASECAMP_USER_AGENT, BASECAMP_CLIENT_ID, BASECAMP_CLIENT_SECRET, BASECAMP_REFRESH_TOKEN overrides the file. See .env.example.

Notes

• Access tokens expire after ~2 weeks; the server refreshes automatically. If auth breaks, re-run hs-basecamp auth.
• Basecamp has no public keyword-search API; get_recent_activity is the catch-up mechanism (sorted by last update).
• macOS is the verified platform; the code is cross-platform but only macOS is tested in this release.

For maintainers

The repo is the distribution channel — there's no npm publish step.

• Ship an update: commit to main and push. Teammates pick it up by re-running the install command. Tag releases (git tag v0.3.0 && git push --tags) so people can pin versions.
• prepare script runs npm run build on every install, so dist/ is built fresh on the teammate's machine — it stays gitignored and is never committed.
• Local dev: npm install, then npm test (Vitest), npm run build, npm run smoke (live MCP handshake — needs a working config).
• Going fully public later is a single npm publish away (publishConfig.access is already public); switch the install docs to npx hs-basecamp if you do.

License

MIT © HyperSense Software