hubspot-conversations-mcp

MCP server for the HubSpot Conversations API with 1:1 tool parity with the Arcade.dev HubSpot Conversations API toolkit (24 tools). Read conversation threads and messages, send replies, manage threads and channel accounts, and integrate custom channels — from any MCP client (Claude Code, Claude Desktop, 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

Install

Once published to npm, no clone or build is needed — MCP clients run the server straight off the registry with npx.

Interactive setup (recommended)

npx -y hubspot-conversations-mcp setup

The wizard walks you through everything:

1. Token guide — step-by-step instructions for creating a HubSpot private app (Settings → Integrations → Private Apps) with the right scopes: conversations.read, conversations.write, and optionally conversations.custom_channels.read/.write for the custom-channel tools.

2. Token prompt — paste the pat-... token (input is masked; OAuth2 access tokens also work), plus an optional default sender actor ID for replies.

3. Agent selection — choose which AI agents to configure: Claude Desktop, Claude Code, and/or Hermes (Nous Research hermes-agent).

4. Automatic install — each selected agent is configured immediately.

The wizard also works scripted: pipe the answers via stdin (printf 'pat-...\n\n1,3\n' | npx -y hubspot-conversations-mcp setup).

Non-interactive install

npx -y hubspot-conversations-mcp install --client all --token pat-eu1-... --sender-actor-id A-12345

--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 and settings are preserved; a timestamped backup is written first). Restart Claude Desktop afterwards.

• claude-code — runs claude mcp add … -- npx -y hubspot-conversations-mcp for you (prints the command if the claude CLI is unavailable). Add --scope user to register it 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 written first; note that YAML comments are not preserved). Verify with hermes mcp test hubspot-conversations.

Use --dry-run to preview changes without writing anything, --config-path for a non-standard Claude Desktop config location, and --hermes-config-path (or HERMES_CONFIG_PATH) for a non-standard Hermes config location.

Note on tokens: HubSpot private app tokens can only be created in the HubSpot UI — there is no public API to generate them, so the CLI guides you through it instead of doing it for you.

Manual: Claude Code

claude mcp add hubspot-conversations --env HUBSPOT_ACCESS_TOKEN=pat-eu1-... --env HUBSPOT_DEFAULT_SENDER_ACTOR_ID=A-12345 -- npx -y hubspot-conversations-mcp

Manual: Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "hubspot-conversations": {
      "command": "npx",
      "args": ["-y", "hubspot-conversations-mcp"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-eu1-...",
        "HUBSPOT_DEFAULT_SENDER_ACTOR_ID": "A-12345"
      }
    }
  }
}

Prerequisite reminder: HubSpot scopes

The token must belong to a private app (or OAuth2 app) with conversations.read + conversations.write, and conversations.custom_channels.read/.write if you use the custom-channel tools.

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 — the token is collected in the UI and stored in the OS keychain instead of a config file.

Related MCP server: Marketing Events MCP Server

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

Tools (Arcade parity)

Threads

Messages

Inboxes, channels & actors

Custom channels (requires the conversations.custom_channels.* scopes)

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. Arcade-style calls are also supported: pass a stringified JSON request_body (typed fields win on conflict), and call with mode="get_request_schema" to inspect 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
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

• Tool names and parameters mirror Arcade's HubspotConversationsApi toolkit 1:1; list tools additionally accept optional filter/pagination parameters (supersets of Arcade's schemas).

• The client retries once on 429/502/503, honoring Retry-After (capped at 10s).

• Thread assignee endpoints (PUT/DELETE /threads/{id}/assignee) exist in the HubSpot API but are not part of Arcade's toolkit, so they are not exposed as tools. Re-add them in src/tools/threads.ts if needed.