HubSpot MCP bridge for OpenClaw

A small Node.js CLI that runs as an MCP server on stdio (so hosts like OpenClaw can spawn it) and forwards requests to HubSpot’s remote MCP at https://mcp.hubspot.com/ using the official @modelcontextprotocol/sdk Streamable HTTP client with OAuth 2.1 + PKCE.

HubSpot setup (MCP auth app)

HubSpot runs the remote MCP service at https://mcp.hubspot.com/ (Streamable HTTP). You do not deploy or host your own MCP server binary on HubSpot. Instead, you create an MCP auth app in HubSpot: that OAuth client supplies the client ID and client secret this bridge uses to authenticate (OAuth 2.1 with PKCE, as required by HubSpot).

Official walkthrough: Integrate AI tools with the HubSpot MCP server (BETA).

Create the MCP auth app

1. Sign in to HubSpot.
2. Open Development (from the main navigation or app switcher, depending on your account layout).
3. In the left sidebar, open MCP Auth Apps.
4. Click Create MCP auth app.
5. Fill in the form (all can be edited later via Edit info on the app details page):
   • App name — e.g. OpenClaw HubSpot MCP.
   • Description — optional.
   • Redirect URL — must exactly match what you set in HUBSPOT_MCP_REDIRECT_URI when using this bridge (including scheme, host, path, and trailing slash if any).
     • For MCP Inspector testing, HubSpot documents adding http://localhost:6274/oauth/callback/debug as one of your redirect URLs (you can register multiple redirect URLs; the first is the default for some flows).
   • Icon — optional.
6. Click Create. HubSpot opens the app’s details page.

Save your credentials

On the app details page, copy:

• Client ID
• Client secret (if shown; treat it like a password)

Put them into your environment (see Environment), e.g. HUBSPOT_MCP_CLIENT_ID and HUBSPOT_MCP_CLIENT_SECRET in .env. Never commit secrets to git.

Scopes and permissions

You do not pick scopes manually when creating the app. Access is determined by the MCP tools HubSpot exposes and by what the installing user grants at install time, within their HubSpot permissions. If HubSpot adds new MCP capabilities later, users may need to re-install the app to approve new scopes.

Optional: sanity-check with MCP Inspector

To verify OAuth and MCP against HubSpot before using this repo:

1. Install and run MCP Inspector.
2. Set Transport to Streamable HTTP, URL to https://mcp.hubspot.com/, and paste your Client ID / Client secret from the MCP auth app.
3. Use Guided OAuth Flow in the inspector and confirm you can connect and list tools (e.g. get_user_details per HubSpot’s docs).

If the inspector works but this bridge does not, compare redirect URLs and env vars.

Install

npm install
npm run build

typescript and @types/node are dependencies (not only devDependencies) so npm run build works even when dev packages are omitted (e.g. npm install --omit=dev or some minimal environments). Tests still need devDependencies (npm install with no flags, or npm install --include=dev).

Optionally link the binary globally:

npm link

Install on OpenClaw (native plugin)

Complete HubSpot setup (MCP auth app) first so you have a client ID, client secret, and redirect URL that match your .env.

This package is an OpenClaw gateway plugin: when enabled, it loads in-process, connects to HubSpot MCP, and registers each upstream tool as a native OpenClaw tool (same idea as openclaw-mcp-adapter).

Plugin id: asm-hubspot-mcp-client-openclaw (matches package.json name; see openclaw.plugin.json).
Extension entry: package.json → "openclaw": { "extensions": ["./dist/openclaw/plugin.js"] } — you must run npm run build so dist/ exists before OpenClaw loads the package.

Official references: Plugin setup & config, CLI plugins.

1. Build this repo

From a clone of this repository:

cd asm-hubspot-mcp-client-openclaw
npm install
npm run build

Confirm dist/openclaw/plugin.js exists.

2. Install the plugin into OpenClaw

Use the OpenClaw CLI (same machine where the gateway runs).

Option A — Local folder (recommended for development / private GitHub)

Links the directory without copying (adds it to OpenClaw’s plugin load paths):

openclaw plugins install -l /absolute/path/to/asm-hubspot-mcp-client-openclaw

Use the absolute path to the repo root (the folder that contains package.json and openclaw.plugin.json).

Option B — From npm (after you publish this package)

When the package is published to the npm registry under its name (e.g. asm-hubspot-mcp-client-openclaw):

openclaw plugins install asm-hubspot-mcp-client-openclaw
# optional: pin the resolved version
openclaw plugins install asm-hubspot-mcp-client-openclaw --pin

OpenClaw installs registry packages with npm install --ignore-scripts; your published tarball should include a prebuilt dist/ (run npm run build before npm publish).

3. Enable the plugin

openclaw plugins enable asm-hubspot-mcp-client-openclaw

Check that it appears:

openclaw plugins list
openclaw plugins info asm-hubspot-mcp-client-openclaw

If something fails to load, run:

openclaw plugins doctor

4. Configure plugin options (optional)

Plugin-specific settings go under plugins.entries.asm-hubspot-mcp-client-openclaw.config in ~/.openclaw/openclaw.json (or your OpenClaw state directory if OPENCLAW_STATE_DIR is set). Example:

{
  plugins: {
    entries: {
      "asm-hubspot-mcp-client-openclaw": {
        enabled: true,
        config: {
          toolPrefix: "hubspot",
          // sessionPath: "/optional/custom/path/session.json",
          // hubspotMcpUrl: "https://mcp.hubspot.com/"
        }
      }
    }
  }
}

Config key	Purpose
toolPrefix	Prefix for tool names (default hubspot → e.g. hubspot_get_user_details). Use "" for no prefix.
sessionPath	Override OAuth session JSON path (else HUBSPOT_MCP_TOKEN_PATH or default under ~/.config/hubspot-mcp-bridge/).
hubspotMcpUrl	Override HubSpot MCP base URL (else HUBSPOT_MCP_URL or https://mcp.hubspot.com/).

Exact JSON shape may vary slightly by OpenClaw version; align with your existing plugins.entries structure.

5. Set environment variables for the gateway

The plugin uses the same variables as the CLI. The OpenClaw gateway process must see them (export in the shell that starts the gateway, a process manager EnvironmentFile, etc.):

• HUBSPOT_MCP_CLIENT_ID (required)
• HUBSPOT_MCP_CLIENT_SECRET (if your HubSpot app uses a secret)
• HUBSPOT_MCP_REDIRECT_URI (must match your HubSpot MCP auth app), unless you only use env-injected tokens (see Environment)

Optional: HUBSPOT_MCP_TOKEN_PATH, HUBSPOT_MCP_URL, HUBSPOT_MCP_ACCESS_TOKEN, HUBSPOT_MCP_REFRESH_TOKEN.

6. Authenticate once (session file)

Before relying on the plugin, complete OAuth so the session file exists (same paths as the CLI):

cd /absolute/path/to/asm-hubspot-mcp-client-openclaw
set -a && source .env && set +a   # or export vars manually
npm run build
node dist/cli.js auth
# complete browser flow, then:
node dist/cli.js auth --code '<authorization-code>'
node dist/cli.js ping            # should report tool count

Alternatively inject HUBSPOT_MCP_ACCESS_TOKEN / HUBSPOT_MCP_REFRESH_TOKEN into the gateway environment and skip the file.

7. Restart the gateway

Restart OpenClaw so the plugin loads with your env and config, for example:

openclaw gateway restart

(Use the restart command your OpenClaw version documents if this differs.)

Plugin vs stdio MCP server

Mode	Use when
Plugin (asm-hubspot-mcp-client-openclaw id)	You want HubSpot tools registered inside the OpenClaw gateway (in-process). Follow this section.
hubspot-mcp-bridge CLI serve	You configure OpenClaw (or another host) to spawn a stdio MCP subprocess — see OpenClaw configuration (stdio MCP) below.

Use one approach for a given setup, not both.

Troubleshooting

• dist/ missing: Run npm run build in this repo before openclaw plugins install -l or before publishing.
• Plugin id mismatch warning: OpenClaw expects the manifest id to match the npm package name. This repo keeps them in sync via src/openclaw/plugin-id.ts (reads package.json) and tests (npm test). Use plugins.entries.<package-name> (e.g. asm-hubspot-mcp-client-openclaw). If you enabled an older id, disable it and enable the matching entry, and merge any config.
• 401 / no tools: Confirm env vars reach the gateway and that auth + ping work from the CLI on the same host.

Stale hubspot-mcp-bridge / “Config invalid” / plugins.allow

Older instructions used the plugin id hubspot-mcp-bridge. The id now must match package.json name: asm-hubspot-mcp-client-openclaw. If your config still mentions hubspot-mcp-bridge, OpenClaw may report:

• plugins.entries.hubspot-mcp-bridge: plugin not found … stale config entry ignored
• plugins.allow: plugin not found: hubspot-mcp-bridge
• Config invalid

Fix:

1. Edit ~/.openclaw/openclaw.json (or your OPENCLAW_STATE_DIR config):

   • Under plugins.allow (if present): remove hubspot-mcp-bridge. Add asm-hubspot-mcp-client-openclaw if your setup uses an explicit allowlist and the new id is not already listed.
   • Under plugins.entries: delete the hubspot-mcp-bridge key. If you had config there, recreate it under asm-hubspot-mcp-client-openclaw (same shape as in Configure plugin options under Install on OpenClaw above).

2. Run:

   openclaw doctor --fix
   

3. From this repo (after npm run build):

   openclaw plugins install -l .
   openclaw plugins enable asm-hubspot-mcp-client-openclaw
   

4. Restart the gateway.

If anything still references hubspot-mcp-bridge except the CLI binary name hubspot-mcp-bridge in package.json bin, remove or rename it in OpenClaw config only.

Environment

See .env.example. Minimum for OAuth:

• HUBSPOT_MCP_CLIENT_ID
• HUBSPOT_MCP_CLIENT_SECRET (if your app is confidential)
• HUBSPOT_MCP_REDIRECT_URI (must match the HubSpot app)

Optional:

• HUBSPOT_MCP_TOKEN_PATH — session file (tokens, PKCE verifier, discovery cache). Default: ~/.config/hubspot-mcp-bridge/session.json.
• HUBSPOT_MCP_ACCESS_TOKEN / HUBSPOT_MCP_REFRESH_TOKEN — skip the session file and inject tokens (useful in containers or secret managers). If HUBSPOT_MCP_REDIRECT_URI is omitted but an access token is set, https://localhost/ is used as a placeholder for OAuth metadata only; you should still set a real redirect when using auth.

Headless authentication

1. Start the flow (prints the HubSpot authorize URL to stdout; no browser is opened on this machine):

   set -a && source .env && set +a
   hubspot-mcp-bridge auth
   

2. Open that URL in a browser (any device), complete install/consent, then copy the authorization code from the redirect (or from HubSpot’s UI, depending on your redirect setup).

3. Exchange the code:

   hubspot-mcp-bridge auth --code <code>
   # or: HUBSPOT_MCP_AUTH_CODE=<code> hubspot-mcp-bridge auth
   # or: echo '<code>' | hubspot-mcp-bridge auth
   

Tokens are written to the session file unless you use env-injected tokens only.

Commands

Command	Purpose
hubspot-mcp-bridge or hubspot-mcp-bridge serve	Run the stdio MCP bridge (used by OpenClaw).
hubspot-mcp-bridge auth	OAuth: print URL, then exchange code with --code / env / stdin.
hubspot-mcp-bridge logout	Clear the session file (tokens, PKCE verifier, discovery cache) so you can auth again—e.g. after HubSpot MCP scope/tool changes or to switch accounts.
hubspot-mcp-bridge ping	Connect upstream and list tool count (sanity check).

If you use HUBSPOT_MCP_ACCESS_TOKEN / HUBSPOT_MCP_REFRESH_TOKEN, logout only clears the file; unset those env vars for a full reset.

OpenClaw configuration (stdio MCP)

If you prefer not to use the native plugin, you can configure OpenClaw to spawn this CLI as an stdio MCP server. Point command at the built CLI and pass the same env vars. Example:

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["/absolute/path/to/asm-hubspot-mcp-client-openclaw/dist/cli.js"],
      "transport": "stdio",
      "env": {
        "HUBSPOT_MCP_CLIENT_ID": "${HUBSPOT_MCP_CLIENT_ID}",
        "HUBSPOT_MCP_CLIENT_SECRET": "${HUBSPOT_MCP_CLIENT_SECRET}",
        "HUBSPOT_MCP_REDIRECT_URI": "${HUBSPOT_MCP_REDIRECT_URI}",
        "HUBSPOT_MCP_TOKEN_PATH": "${HUBSPOT_MCP_TOKEN_PATH}"
      }
    }
  }
}

Restart the OpenClaw gateway after changes. Exact config keys depend on your OpenClaw version.

Development

npm test
npm run build

npm test includes a check that openclaw.plugin.json id equals package.json name and matches the runtime plugin entry. That alignment is what OpenClaw expects; if you rename the package, update the manifest id and let tests confirm—otherwise users see a plugin id mismatch warning.

Disclosure (AI-assisted development)

This repository was developed with AI coding tools (LLM-based assistants) and reviewed by humans before publication. That mix is increasingly common: the tools accelerate implementation, while maintainers remain responsible for correctness, security review, and fit for purpose.

You should still run your own review, tests, and security assessment before using this software with real HubSpot data or in production—especially for OAuth tokens, API access, and OpenClaw gateway configuration.

There is no single industry-standard disclaimer; transparency about AI assistance plus human oversight matches what many open-source and corporate AI policies suggest.

References

• Integrate AI tools with the HubSpot MCP server (BETA)
• Model Context Protocol