HubSpot

ohneben's HubSpot MCP

License & checks

MCP registries

The most complete HubSpot MCP server there is. Run your entire

HubSpot account in plain language from Claude,

Cursor, or any other MCP client.

This Model Context Protocol server exposes the

**whole public HubSpot API — all 1,076 endpoints across 102 APIs, in 687

tools** — CRM, CMS, Marketing, Automation, Conversations, Commerce, Files,

Settings, Webhooks and more, generated straight from HubSpot's own OpenAPI

definitions. Endpoints HubSpot repeats per object type are one tool each

(crm_objects_search with objectType: "deals" instead of 32 separate search

tools), and every tool description says when to use it. Every tool is

safety-categorized (🟢 read-only / 🟡 write / 🔴 destructive) and — unique to

this server — hub & plan aware: HubSpot publishes which hub and tier every

API needs (Free / Starter / Professional / Enterprise), and this server carries

that straight into each tool plus a live capability report for *your*

portal. It runs over stdio (Claude Desktop and other local launchers) or

Streamable HTTP (hosted in Docker), and ships with retries, client-side rate

limiting tuned to HubSpot's burst caps, and request timeouts so it holds up

against a live account.

Why you'll want this

Some MCP servers just forward a slice of the API. This one is built to be **safe

to hand to an LLM, complete, and easy to run for real**:

How it compares

There are a few ways to reach HubSpot from an AI assistant today. Here's how this

server stacks up against the alternatives:

✅ = yes · ➖ = partial / not documented · ❌ = no. Compiled from each

project's public documentation; this is an unofficial project, not affiliated

with HubSpot or the projects listed. Tool counts are approximate and move as

APIs evolve.

The short version: the official remote server is a great managed on-ramp

but covers a handful of curated tools. The community servers are solid but

CRM-centric, without plan awareness or safety guardrails. This one gives you

the entire public API, hub/plan awareness no one else has, **both

transports, a production Docker deployment, and curated safety

categories** — self-hosted, on your token, MIT.

What you can do

Once it's connected, ask your assistant things like:

• "Find jane@example.com, show her company, open deals and the last emails we exchanged."
• "Create a $12,000 deal 'Acme expansion' in the Sales pipeline, stage Qualified, associated with Acme Corp."
• "Search contacts created this month with lifecycle stage MQL and add them to the 'Q3 nurture' list."
• "Which HubDB tables exist? Add a row to 'pricing' and publish the table."
• "Clone last month's newsletter as a draft — don't publish."
• "Upload this CSV and start a contact import mapped to email + first name."
• "What can my token do? Check my API usage and which scopes are missing for HubDB." *(→ hubspot_get_capabilities)*
• "Merge these two duplicate contacts — after showing me both records first."

Tools are generated automatically from HubSpot's specs and grouped into

🟢 read-only, 🟡 write and 🔴 destructive — so a well-behaved host can treat each

group differently.

How it works

Claude / Cursor / any MCP client  ──MCP──►  this server  ──HTTPS──►  api.hubapi.com (your portal)

The server parses 104 bundled OpenAPI definitions (fetched from HubSpot's public

API index, which also publishes per-API hub/tier requirements) into MCP

tools — resolving $refs, guarding against recursive schemas, merging

endpoints that only differ by object type into one tool, deriving clean names

like crm_objects_search and hubdb_tables_create_table, and tagging each

tool with a curated safety category, its plan requirement and its OAuth scopes.

Your access token is injected server-side on every request; the model never

sees or handles it.

Hub & plan awareness

HubSpot isn't one API — what you can call depends on which hubs (Marketing,

Sales, Service, Content, Commerce, Operations) and which tier (Free,

Starter, Professional, Enterprise) the portal has, plus the scopes granted

to your token. This server is built around that reality:

1. Every tool description carries the requirement, from HubSpot's own index:

```

🟢 READ-ONLY · Get all published tables.

Use to page through tables: pass limit, then the after cursor from paging.next.after for the next page.

…

Plan: Professional tier of Marketing Hub / Content Hub. Scopes: hubdb.

Endpoint: GET /cms/v3/hubdb/tables (Hubdb API, CMS)

```

Consolidated tools state it per value: crm_objects_list lists which

object types need a paid tier in its objectType parameter.

1. An access check runs when the server starts. HubSpot has no API that

returns a portal's subscription, so the server combines what it can

observe: the token's granted scopes, and one cheap read per paid-tier or

beta group (up to about 30 API calls; plan gates only surface as 403s).

Every group gets a status: available, missing_scopes, blocked (plan

tier, user permission, or a 401 from an API that does not accept this kind

of token) or unverified. HubSpot's error details count: a 403 that names

scopes the token lacks is a missing scope, while MISSING_SCOPES for an

object whose scopes the token already holds is how HubSpot answers a plan

gate, so that is reported as blocked. A read

that succeeds proves read access only; a paid-tier API can still refuse

writes, and the report says so. The model receives a summary in

the server instructions, hubspot_search_endpoints marks each result (and

takes usable_only: true), and hubspot_get_capabilities returns the full

report with reasons, "unlockedByScopes": "13/16" counts and the scopes to

add; refresh: true runs it again. Turn it off with

HUBSPOT_CAPABILITY_CHECK=false.

1. 403s come back with the fix: missing scope → the exact scope name and

where to grant it; plan-gated API → the tier HubSpot requires.

Requirements

• A HubSpot account and a service key (or an existing legacy private

app token); see [Get your API credentials](#get-your-api-credentials).

• Docker (Docker Desktop on macOS/Windows) for the quick start below — or

Node.js ≥ 18 to [run from source](#run-from-source-stdio-no-docker).

Quick start (Docker)

1. Add your credentials. Copy the example config and fill it in:

cp .env.example .env
# edit .env → set HUBSPOT_ACCESS_TOKEN
#           → set MCP_AUTH_TOKEN. REQUIRED unless HOST is a loopback address,
#             otherwise the server refuses to start: MCP_AUTH_TOKEN=$(openssl rand -hex 32)

2. Start the server:

docker compose up -d --build

The bundled docker-compose.yml binds to 127.0.0.1:8765 only, so the server is

reachable from your machine but not the network.

3. Confirm it's running:

curl -s http://localhost:8765/health
# → {"status":"ok","server":"hubspot-mcp"}

4. Connect your MCP client. The MCP endpoint is http://localhost:8765/mcp.

• Claude Desktop — add a custom connector (Settings → Connectors) pointing

at the URL, or bridge it locally with

mcp-remote. Add this under

mcpServers in your config, then fully quit and reopen the app:

```json

{

"mcpServers": {

"hubspot": {

"command": "npx",

"args": [

"mcp-remote",

"http://localhost:8765/mcp",

"--header", "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"

]

}

}

}

```

(Drop the --header line only if the server runs without a token, which it

allows on a loopback bind alone.)

• Claude Code — one command:

```bash

claude mcp add --transport http hubspot http://localhost:8765/mcp

```

• Claude Cowork — shares Claude Code's MCP config, so the command above makes

the tools available there too.

> Tip: by default the model sees 6 tools and reaches every endpoint through

> search → inspect → invoke. For one tool per endpoint set

> HUBSPOT_TOOL_MODE=all (690 tools) and trim it with HUBSPOT_INCLUDE_GROUPS

> (e.g. contacts,companies,deals,tickets,lists) — see

> [Context footprint](#context-footprint) for measured numbers per

> configuration.

Prefer a prebuilt image?

Every push to main publishes a ready-to-run image to the GitHub Container

Registry, so you can skip the local build entirely:

docker run -d --name hubspot-mcp -p 127.0.0.1:8765:8765 --env-file .env \
  ghcr.io/ohneben/hubspot-mcp:latest

Get your API credentials

The recommended way is a service key, HubSpot's replacement for legacy

private apps:

1. In HubSpot, open Settings → Integrations → Service Keys (or

Development → Keys → Service Keys) and create a key. You need super

admin rights or the *Developer tools access* permission.

1. Select the scopes you want the assistant to reach. Scopes map 1:1 to tool

groups: grant read scopes (crm.objects.contacts.read, …) for a reporting

setup, and add write scopes only where you want changes.

1. Copy the key (pat-…) → HUBSPOT_ACCESS_TOKEN in .env. It is sent as a

bearer token exactly like a private app token, so nothing else changes.

Notes:

• Service keys are in public beta and differ from private apps in three

ways that matter here: they do not support GraphQL (set

HUBSPOT_ENABLE_GRAPHQL=false), rotation keeps the old key valid for a

7-day grace period, and the scope and usage figures in the capability report

may be incomplete for them.

• Existing private app tokens keep working. HubSpot stops the creation of

new legacy private apps (existing portals from 26 October 2026, new portals

from 28 September 2026); apps already created are not affected. A private

app is still the only option here if you rely on the GraphQL tool.

• OAuth access tokens work too (for apps you've built) — but they expire

after ~30 minutes and this server does not refresh them; a service key or

private app token is the right fit for a long-running server.

• The token determines the portal — no portal ID needed.
• EU data residency: if your portal lives in HubSpot's EU data center, set

HUBSPOT_BASE_URL=https://api-eu1.hubapi.com.

Configuration

Everything is set in .env (copied from .env.example):

After changing .env, reload with docker compose up -d --force-recreate.

Run npm run list-tools (no credentials needed) to print the full catalog, the

per-category counts, and every group key you can filter on — add --names to

list all 687 tool names with the endpoint each one calls.

Tool safety categories

Each tool's description starts with one of these banners and carries the matching

MCP annotations:

That's 302 read-only · 305 write · 80 destructive = 687 endpoint tools

(443 · 485 · 148 = 1,076 endpoints), plus the three power tools below. Hosts

that respect annotations (Claude included) can require confirmation for

destructiveHint tools and trust readOnlyHint tools automatically. Prefer to

lock it down further? Set HUBSPOT_READ_ONLY=true to expose *only* the 302

read-only tools (plus the 🟢 capability and GraphQL tools).

Coverage by area (APIs / endpoints by 🟢 read / 🟡 write / 🔴 destructive / tools)

Context footprint

What does the tool list cost in model context? Measured on the bundled specs

(tools/list JSON payload; tokens ≈ chars ÷ 3.6):

In discovery mode each hubspot_get_endpoint lookup adds only the schema the

model asked for: about 350 tokens for a typical endpoint, up to ~12k for the

largest CMS page bodies.

¹ HUBSPOT_INCLUDE_GROUPS=contacts,companies,deals,tickets,lists,properties,associations,pipelines,crm-owners,notes,tasks,calls,emails,meetings

How to read that:

• Discovery mode loses no coverage: all 1,076 endpoints stay callable

through search → inspect → invoke, at the cost of one or two extra calls the

first time the model uses an endpoint.

• Clients with tool search / deferred loading (Claude Code, claude.ai

connectors) load tool definitions on demand, so HUBSPOT_TOOL_MODE=all works

well there; narrow it with a HUBSPOT_INCLUDE_GROUPS preset and/or

HUBSPOT_READ_ONLY=true.

• Responses consume context too. Cap outliers with

HUBSPOT_MAX_RESPONSE_CHARS (e.g. 40000) and request only the

properties you need on CRM reads.

• Oversized inline schemas are already handled: the four pathological

recursive schemas (list filters, workflow definitions — ~1.7 MB *each*

fully inlined) are budget-pruned to ≤24 KB with their top levels intact.

Input schemas also drop examples and any prose below the body's own fields;

every field, type, enum and required list stays.

The power tools

Besides the generated endpoint tools, the server ships four hand-built ones:

• hubspot_get_capabilities 🟢 — the access report described

[above](#hub--plan-awareness). Returns the startup check without new API

calls; refresh: true runs it again.

• hubspot_graphql_query 🟢 — HubSpot's CRM GraphQL API

(POST /collector/graphql). Query-only by design (HubSpot exposes no

mutations), so it stays available even in read-only mode. Requires the

collector.graphql_query.execute scope and Marketing/Content Hub Pro+.

• hubspot_api_request 🔴 — raw escape hatch for any path on the HubSpot

host (new betas, undocumented corners). Same auth injection, throttling and

retries. Hidden in read-only mode.

• Discovery mode (the default) — replaces the 687

endpoint tools with hubspot_search_endpoints →

hubspot_get_endpoint → hubspot_invoke_endpoint over the same registry.

All filters (groups, beta, read-only) still apply; in read-only mode the

invoke tool physically cannot reach a write because writes aren't in the

registry.

Upgrading from 1.x

2.0 merges endpoints that HubSpot repeats per object type into one tool with a

selector argument. Every endpoint is still reachable and sends the same

request; only tool names and a few argument names change. Update saved

prompts, client allowlists and permission rules that name tools. Group keys

for HUBSPOT_INCLUDE_GROUPS / HUBSPOT_EXCLUDE_GROUPS (contacts, deals,

pages, …) are unchanged.

Unchanged: endpoints only one type has (contacts_gdpr_delete, landing page

folders, blog post drafts and revisions, blog create/update, whose bodies differ

per resource). npm run list-tools -- --names prints every tool with the endpoint

it calls. POST endpoints that publish, schedule or restore existing content are

now labelled 🟡 *updates data* instead of *creates data*.

Two defaults change as well: HUBSPOT_TOOL_MODE is now discovery (set it to

all to expose the endpoint tools themselves), and the server runs the access

check at startup, which costs up to about 30 API calls per start

(HUBSPOT_CAPABILITY_CHECK=false turns it off).

Run from source (stdio, no Docker)

Prefer the classic stdio mode for Claude Desktop? Build it locally:

npm install
npm run build

Then point Claude Desktop at the compiled entrypoint in

claude_desktop_config.json:

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/Hubspot-MCP/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-…"
      }
    }
  }
}

Keeping the specs current

The bundled files under spec/ are the source of truth for the tools. They are

fetched from HubSpot's own public API index

(https://api.hubspot.com/public/api/spec/v1/specs), which lists every public

API with per-version OpenAPI documents and the hub/tier requirements this

server bakes into tool descriptions. spec/catalog.json records what was

fetched (API, version, stage, beta flag, requirements, docs links).

To refresh against HubSpot's latest:

npm run fetch-specs   # rewrites spec/*.json + spec/catalog.json
npm run build && npm run list-tools

New endpoints become new tools automatically — no code changes. The fetch

script prefers each API's stable classic version (v1/v3/v4) and falls back

to dated or beta versions when that's all HubSpot offers; a couple of APIs are

pinned to bundle multiple genuinely-different versions (OAuth v1 + v3,

Communication Preferences v3 + v4).

Development

npm install
npm run build       # compile TypeScript → dist/
npm test            # run the Vitest suite (160 tests)
npm run list-tools  # print the categorized tool catalog (no credentials needed)
npm run fetch-specs # refresh spec/ from HubSpot's public API index

CI builds and tests every push across Node 20 and 22; pushes to main also

publish a Docker image to the GitHub Container Registry.

Notes & conventions

• Transports: MCP_TRANSPORT=stdio (default) for local launchers;

MCP_TRANSPORT=http for the always-on Streamable-HTTP server the Docker image

runs.

• Paging: CRM list tools use cursor paging — pass limit and the after

cursor from paging.next.after. Ask for the properties you need via the

properties parameter (arrays become repeated query params).

• Selectors: consolidated tools take objectType (crm_objects_*),

pageType (cms_pages_*) or blogResource (cms_blog_*). objectType

accepts names (contacts, line_items), objectTypeIds (0-3) and custom

object types (2-12345).

• Search: crm_objects_search and the other *_search tools take a JSON

body with filterGroups, sorts, query, properties, limit and

after. HubSpot caps search at ~5 req/s per token — the built-in search

throttle keeps you under it.

• Batch tools (crm_objects_batch_read, crm_objects_batch_create, …) are

the efficient way to touch many records — prefer them over loops of single

calls.

• Associations: use the v4 association tools (associations_*) to link

records, with optional labels via the association-schema tools.

• File uploads: multipart tools accept file fields as

{"fileName": "report.pdf", "contentBase64": "…"} (or content for plain

text); other fields are sent as regular form fields, objects as JSON strings.

• Deletes are archives for CRM objects (recycle bin, ~90 days) — the truly

permanent ones are the 🔴 gdpr_delete purge tools and record merges.

• Rate limits: HubSpot enforces burst caps per 10 s (private apps:

100–200/10 s depending on plan; OAuth apps ~110/10 s) plus daily caps. The

server self-throttles at HUBSPOT_MAX_REQUESTS per window and retries any

429 it still receives, honoring Retry-After. Check real usage anytime via

hubspot_get_capabilities.

• Request bodies: write tools take a body argument; its schema is resolved

from the spec and shown to the model (e.g. crm_objects_create expects

{"properties": {…}}).

• Beta APIs (developer preview / public beta) are included by default and

labelled ⚠️ in descriptions; hide them with HUBSPOT_INCLUDE_BETA=false.

Security

• Your access token lives only in .env, which is git-ignored. **Never commit

real secrets.** The token grants whatever its scopes allow — if it leaks,

expire it in Settings → Integrations → Service Keys (or Private Apps

for a legacy token).

• The HTTP endpoint refuses to start unauthenticated once it is bound beyond

this machine. Set MCP_AUTH_TOKEN (openssl rand -hex 32) and send it as an

Authorization: Bearer <token> header, ideally behind TLS. A loopback bind

still needs no token, and is additionally protected against DNS rebinding by

a Host header check.

• Destructive tools (delete / merge / GDPR purge) and send tools

(marketing & transactional email, sequences) carry the right annotations so a

well-behaved host prompts before acting — keep that confirmation on, or run

with HUBSPOT_READ_ONLY=true.

• Scope the blast radius at the source: grant the service key only the scopes

you actually need — the startup access check and hubspot_get_capabilities

tell you what's missing when you want more. The check itself only reads.

See [SECURITY.md](./SECURITY.md) for the full policy and how to report a

vulnerability.

Credits & license

An unofficial community integration for HubSpot;

not affiliated with or endorsed by HubSpot. Built on the

Model Context Protocol. Tools are generated

from HubSpot's public OpenAPI definitions. Licensed under the

[MIT License](./LICENSE.md).