Skip to main content
Glama
HubSpot MCP

HubSpot MCP

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
HOSTNoHTTP bind address0.0.0.0
PORTNoHTTP listen port8765
MCP_HTTP_PATHNoHTTP MCP route/mcp
MCP_TRANSPORTNostdio or httpstdio
HUBSPOT_BASE_URLNoUse https://api-eu1.hubapi.com for EU data residencyhttps://api.hubapi.com
HUBSPOT_SPEC_DIRNoLoad OpenAPI files from a different directory
MCP_SHARED_TOKENNoRequire Authorization: Bearer <token> on /mcp
HUBSPOT_READ_ONLYNoExpose only read-only toolsfalse
HUBSPOT_TOOL_MODENoall or discoveryall
HUBSPOT_TIMEOUT_MSNoPer-attempt request timeout30000
HUBSPOT_GRAPHQL_URLNoOverride GraphQL endpoint
HUBSPOT_MAX_RETRIESNoRetries on 429 / 5xx / network errors3
HUBSPOT_ACCESS_TOKENYesPrivate-app token (pat-โ€ฆ) or OAuth access token
HUBSPOT_INCLUDE_BETANoInclude beta APIstrue
HUBSPOT_MAX_REQUESTSNoClient-side requests per window (0 disables throttling)100
HUBSPOT_ENABLE_GRAPHQLNoExpose CRM GraphQL query tooltrue
HUBSPOT_EXCLUDE_GROUPSNoHide these groups
HUBSPOT_INCLUDE_GROUPSNoOnly expose these groups (comma-separated, wildcards allowed)
HUBSPOT_RATE_WINDOW_MSNoRate-limit window in ms10000
HUBSPOT_ENABLE_RAW_REQUESTNoExpose raw-request escape hatchtrue
HUBSPOT_MAX_RESPONSE_CHARSNoTruncate responses longer than N chars (0 = never)0
HUBSPOT_SEARCH_MAX_REQUESTSNoExtra throttle for /search endpoints (0 disables)4
HUBSPOT_SEARCH_RATE_WINDOW_MSNoSearch throttle window1000

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

HubSpot API server: tools map 1:1 to HubSpot's public REST endpoints (CRM, CMS, Marketing, Automation, Commerce, Files, Settings, Webhooks).

Every tool description starts with a safety banner that matches its annotations: ๐ŸŸข READ-ONLY (no changes), ๐ŸŸก WRITE (creates, updates, links or sends), ๐Ÿ”ด DESTRUCTIVE (deletes, merges, purges). Confirm ๐Ÿ”ด tools and 'sends messages' tools with the user before calling them.

The server checked this token's access when it started. Access check at 2026-11-18T23:50:19.875Z: 1 of 102 API groups are usable with this token. Blocked by plan tier, permissions or token type: aeo, payment-links. Not verified: account-info, actions-v4, app-uninstalls, appointments, associations, associations-schema, audit-logs, authors, automation-v4, blog-settings, business-units, calling-extensions, calls, campaigns-public-api, carts, cms-content-audit, commerce-payments, commerce-subscriptions, communications, companies, contacts, contracts, conversations, courses, crm-owners and 74 more. Prefer tools in usable groups; hubspot_get_capabilities gives the reason and the scopes to add for each group.

Prefer *_search and batch tools over loops of single calls. CRM list tools page with limit plus the after cursor; request only the properties you need.

CRM deletes archive records to the recycle bin for about 90 days. Merges and gdpr_delete purges are permanent.

Discovery mode: find an endpoint with hubspot_search_endpoints, read its input schema with hubspot_get_endpoint, then call it with hubspot_invoke_endpoint.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
hubspot_search_endpointsA

๐ŸŸข READ-ONLY ยท endpoint catalog search

Search this server's catalog of 687 HubSpot endpoint tools by keyword, group, area or safety category. Returns one compact line per tool (name, method+path, category, API; consolidated tools also list the values of their selector argument, e.g. objectType). Each line also says whether this token can use the tool, from the access check the server ran at startup.

Workflow: search here โ†’ hubspot_get_endpoint for the input schema โ†’ hubspot_invoke_endpoint to call it.

hubspot_get_endpointA

๐ŸŸข READ-ONLY ยท endpoint details

Return one endpoint's full description, safety category, plan/scope requirements and JSON input schema. Use the exact tool name from hubspot_search_endpoints.

hubspot_invoke_endpointA

๐ŸŸก WRITE-CAPABLE ยท invoke a catalog endpoint

Call any endpoint in the registry by name with arguments matching its input schema (fetch it first via hubspot_get_endpoint).

The registry includes ๐ŸŸก write and ๐Ÿ”ด destructive endpoints. Check the endpoint's banner first and confirm with the user before any destructive call (delete / merge / GDPR purge / send).

hubspot_get_capabilitiesA

๐ŸŸข READ-ONLY ยท HubSpot account access report

Reports what THIS HubSpot account and token can use: portal details, granted scopes, daily API usage, and for every API group an access status (available, missing_scopes, blocked, unverified) with the reason, the plan tier HubSpot requires and the scopes that would unlock it.

The server already ran this check at startup, probing each paid-tier or beta group with one cheap read, so a plain call returns that result without new API calls. Pass refresh=true after the token's scopes or the portal's subscription changed. probe_groups live-probes further groups, one API call each.

hubspot_graphql_queryA

๐ŸŸข READ-ONLY ยท query ยท CRM GraphQL ยท POST /collector/graphql

Run a GraphQL query against HubSpot's CRM data graph and return the JSON result. Fetches records, properties and associations across objects in one round-trip โ€” use it when a REST tool would need several calls or returns too much.

HubSpot's GraphQL endpoint supports queries only (no mutations), so this cannot change account data. Endpoint: https://api.hubapi.com/collector/graphql. Plan: Marketing Hub or Content Hub Professional/Enterprise. Scopes: collector.graphql_query.execute. Not available with a HubSpot service key; it needs a private app or OAuth token. Example: {"query": "query { CRM { contact_collection(limit: 3) { items { email firstname associations { company_collection__primary { items { name } } } } } } }"}

hubspot_api_requestA

๐Ÿ”ด ADVANCED ยท raw HubSpot API request

Perform an arbitrary HTTP request against the HubSpot API host โ€” the escape hatch for brand-new or beta endpoints that don't have a dedicated tool (yet). Auth, rate limiting, timeouts and retries are still handled server-side.

Host is fixed to https://api.hubapi.com; pass only the path (e.g. "/crm/v3/objects/contacts"). PREFER the dedicated tools: they carry accurate schemas and safety categories. This tool can execute ANY method, including destructive ones โ€” state the method and path clearly and get user confirmation for writes/deletes.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A4.2/5.0

Scored across 6 tools

Disambiguation4/5

The search โ†’ get_endpoint โ†’ invoke_endpoint pipeline has clearly staged, non-overlapping purposes, and capabilities/graphql are distinct. The main fuzziness is between hubspot_invoke_endpoint, hubspot_graphql_query and hubspot_api_request, which are all ways to execute calls; descriptions mitigate this by recommending the dedicated path and marking api_request as an escape hatch, but an agent could still pick the wrong one.

Naming Consistency4/5

All six tools share the hubspot_ prefix and snake_case, and four follow a clean verb_noun pattern (search_endpoints, get_endpoint, invoke_endpoint, get_capabilities). The two exceptions, hubspot_graphql_query and hubspot_api_request, are noun phrases rather than verb-first, a minor deviation that remains readable.

Tool Count5/5

Six tools is exactly right for a gateway that fronts 687 underlying endpoints โ€” a small, well-earned surface that avoids flooding the agent with individual tools. Each tool has a distinct role in the discovery, inspection, invocation or capability-checking workflow.

Completeness5/5

The set covers the full lifecycle: discovery (search), schema inspection (get_endpoint), execution (invoke_endpoint), access/permission reporting (get_capabilities), plus GraphQL for multi-object reads and a raw HTTP escape hatch for unregistered or beta endpoints. No obvious dead ends remain for reaching any HubSpot API capability.

Maintenance

ActivityStale
ResponsivenessNo recent community issues