HubSpot MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HOST | No | HTTP bind address | 0.0.0.0 |
| PORT | No | HTTP listen port | 8765 |
| MCP_HTTP_PATH | No | HTTP MCP route | /mcp |
| MCP_TRANSPORT | No | stdio or http | stdio |
| HUBSPOT_BASE_URL | No | Use https://api-eu1.hubapi.com for EU data residency | https://api.hubapi.com |
| HUBSPOT_SPEC_DIR | No | Load OpenAPI files from a different directory | |
| MCP_SHARED_TOKEN | No | Require Authorization: Bearer <token> on /mcp | |
| HUBSPOT_READ_ONLY | No | Expose only read-only tools | false |
| HUBSPOT_TOOL_MODE | No | all or discovery | all |
| HUBSPOT_TIMEOUT_MS | No | Per-attempt request timeout | 30000 |
| HUBSPOT_GRAPHQL_URL | No | Override GraphQL endpoint | |
| HUBSPOT_MAX_RETRIES | No | Retries on 429 / 5xx / network errors | 3 |
| HUBSPOT_ACCESS_TOKEN | Yes | Private-app token (pat-โฆ) or OAuth access token | |
| HUBSPOT_INCLUDE_BETA | No | Include beta APIs | true |
| HUBSPOT_MAX_REQUESTS | No | Client-side requests per window (0 disables throttling) | 100 |
| HUBSPOT_ENABLE_GRAPHQL | No | Expose CRM GraphQL query tool | true |
| HUBSPOT_EXCLUDE_GROUPS | No | Hide these groups | |
| HUBSPOT_INCLUDE_GROUPS | No | Only expose these groups (comma-separated, wildcards allowed) | |
| HUBSPOT_RATE_WINDOW_MS | No | Rate-limit window in ms | 10000 |
| HUBSPOT_ENABLE_RAW_REQUEST | No | Expose raw-request escape hatch | true |
| HUBSPOT_MAX_RESPONSE_CHARS | No | Truncate responses longer than N chars (0 = never) | 0 |
| HUBSPOT_SEARCH_MAX_REQUESTS | No | Extra throttle for /search endpoints (0 disables) | 4 |
| HUBSPOT_SEARCH_RATE_WINDOW_MS | No | Search throttle window | 1000 |
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
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| 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
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 6 tools
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.
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.
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.
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.