hubspot-conversations-mcp

MCP server for the HubSpot Conversations API — 24 tools to read conversation threads and messages, send replies, manage threads and channel accounts, and integrate custom channels, from any MCP client (Claude Code, Claude Desktop, Hermes, etc.).

Covers two HubSpot API surfaces:

• Conversations API (/conversations/conversations/2026-09-beta) — threads, messages, inboxes, channels, actors

• Custom Channels API (/conversations/custom-channels/2026-03) — channel accounts, staging tokens, publishing external messages, delivery status

How authentication works

There is exactly one way to authenticate: per-user OAuth via your organization's broker.

Every user signs in with their own HubSpot login — tokens are issued individually, stored only on their machine (~/.hubspot-conversations-mcp/tokens.json, 0600), revocable per user, and die when the user is deactivated in HubSpot. No shared credentials exist anywhere.

The broker is a small stateless service your org hosts (free on Vercel, api/ in this repo). It is the only place your HubSpot app's client secret lives; it exchanges authorization codes and refreshes tokens, stores nothing, and never sees Conversations data — all API traffic goes directly from the user's machine to HubSpot.

Related MCP server: hubspot-mcp

Org setup (one-time, ~10 minutes)

1. Create a HubSpot app (in a developer account, e.g. as a developer-projects app): use "distribution": "private" and allowlist your portal. The auth block of app-hsmeta.json should look like:

   "auth": {
     "type": "oauth",
     "redirectUrls": ["http://localhost:4573/callback"],
     "requiredScopes": ["oauth", "conversations.read", "conversations.write"],
     "optionalScopes": [],
     "conditionallyRequiredScopes": []
   }

   Deploy the app and note the client ID and client secret from its Auth tab.

2. Deploy the broker to Vercel — one click:

   

   The button clones this repo and prompts for the two environment variables (HUBSPOT_OAUTH_CLIENT_ID, HUBSPOT_OAUTH_CLIENT_SECRET). Alternatively create the Vercel project manually from your fork, or wire up CI deploys via deploy-broker.yml with the VERCEL_TOKEN / VERCEL_ORG_ID / VERCEL_PROJECT_ID repo secrets.

3. Share the broker URL (e.g. https://your-broker.vercel.app) with the team — it is not a secret, and neither is the client ID (the CLI fetches it from the broker's /api/config). Setting HUBSPOT_OAUTH_BROKER_URL org-wide (dotfiles, MDM, onboarding docs) makes all commands flag-free.

Because the app is private-distribution and allowlisted, only your own org's portals can complete a login against your broker — each org runs its own broker with its own app, so tokens never cross organizational trust boundaries.

Per user

Interactive setup (recommended)

npx -y hubspot-conversations-mcp setup

The wizard walks through everything:

1. Broker — asks whether your org already has a broker; if not, it shows the setup guide (and links back here). The URL is verified live against /api/config before continuing.

2. Sign in — your browser opens HubSpot's consent screen; sign in with your own HubSpot login. Tokens land on your machine and auto-refresh through the broker.

3. Agents — pick which AI agents to configure with an arrow-key multiselect (↑/↓ to move, space to toggle): Claude Desktop, Claude Code, and/or Hermes (Nous Research hermes-agent). Each is configured automatically — no credentials are written to any config file.

Manual / scripted

npx -y hubspot-conversations-mcp login --broker-url https://your-broker.vercel.app

npx -y hubspot-conversations-mcp install --client all

--client takes claude-desktop, claude-code, hermes, both (the two Claude clients), all, or a comma-separated combination:

• claude-desktop — merges the server into claude_desktop_config.json (existing servers preserved; timestamped backup first). Restart Claude Desktop afterwards.

• claude-code — runs claude mcp add … -- npx -y hubspot-conversations-mcp (prints the command if the claude CLI is unavailable). Add --scope user to register across all your projects (the setup wizard defaults to this).

• hermes — merges the server into ~/.hermes/config.yaml under mcp_servers with enabled: true (backup first; YAML comments are not preserved). Verify with hermes mcp test hubspot-conversations.

whoami shows the active sign-in, logout removes it. Use --dry-run to preview installs, --config-path / --hermes-config-path for non-standard config locations.

Broker endpoints

One-click bundle for Claude Desktop (MCPB)

The repo ships a manifest.json following Anthropic's MCP Bundle format:

npm run bundle

This produces a .mcpb file. Open it with Claude Desktop (or drag it into Settings → Extensions) for a one-click install. Run npx -y hubspot-conversations-mcp login once first — the extension uses the same per-user sign-in.

Publishing to npm

npm publish

prepublishOnly builds and runs the full test suite first. The published package contains only dist/, manifest.json, README and LICENSE. Bump version in both package.json and manifest.json (and SERVER_VERSION in server.ts) per release.

Configuration

On the broker deployment (never on user machines): HUBSPOT_OAUTH_CLIENT_ID and HUBSPOT_OAUTH_CLIENT_SECRET.

Tools

Threads

Messages

Inboxes, channels & actors

Custom channels (requires the conversations.custom_channels.* scopes on the HubSpot app)

Sending replies

SendConversationMessage only requires thread_id and text. Everything else is derived:

• channel_id / channel_account_id — taken from the thread's originalChannelId / originalChannelAccountId

• recipients — the senders of the latest incoming message (i.e. a normal reply)

• sender_actor_id — falls back to HUBSPOT_DEFAULT_SENDER_ACTOR_ID

Pass any of them explicitly to override. The full request body can also be supplied as a stringified JSON request_body (typed fields win on conflict), and calling with mode="get_request_schema" returns the raw body schema. The same pattern applies to PublishCustomChannelMessage.

Development

npm test           # vitest — unit + in-memory MCP integration tests
npm run typecheck  # tsc --noEmit (CLI + broker functions)
npm run build      # compile to dist/
npm run bundle     # build a .mcpb one-click bundle for Claude Desktop

The integration tests run the full MCP server against a stubbed fetch, so no HubSpot account is needed to develop.

Notes

• The client retries once on 429/502/503 (honoring Retry-After, capped at 10s) and once more with a refreshed token on 401.

• Thread assignee endpoints (PUT/DELETE /threads/{id}/assignee) exist in the HubSpot API but are not currently exposed as tools. Add them in src/tools/threads.ts if needed.