connect-hubspot-mcp
Connect Claude to HubSpot's official remote MCP server for conversational CRM lookups, spot-checks, and small confirmed edits. Covers the MCP connector setup with OAuth and PKCE, what the server's tools can and cannot do, and when to use MCP versus the Agent CLI versus this repo's scripts.
tomgranot · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add TomGranot/hubspot-admin-skills --skill connect-hubspot-mcp技能说明
name: connect-hubspot-mcp description: "Connect Claude to HubSpot's official remote MCP server for conversational CRM lookups, spot-checks, and small confirmed edits. Covers the MCP connector setup with OAuth and PKCE, what the server's tools can and cannot do, and when to use MCP versus the Agent CLI versus this repo's scripts." license: MIT metadata: author: tomgranot version: "2.0" category: audit-planning
Connect Claude to HubSpot via MCP
Set up HubSpot's official remote MCP server so Claude can read and write CRM records conversationally: look up a contact, inspect a company's deals, spot-check the results of a cleanup, without writing a script for every question.
Three Ways to Reach a Portal
This toolkit can talk to HubSpot three ways. They overlap less than they appear to.
| Remote MCP server (this skill) | Agent CLI (/connect-hubspot-agent-cli) | REST scripts (every scripted skill) | |
|---|---|---|---|
| Status | Generally available | Beta | v3/v4 paths, see /audit-api-usage |
| Auth | OAuth as you, via an MCP connector | OAuth as you, or a service key | Service key in .env |
| Best for | Lookups, spot-checks, judgment calls, small edits | Bulk and admin work driven from the terminal | Repeatable runs with a CSV audit trail and an abort threshold |
| Bulk reads | 200 records per page | Paginated, JSONL out | Paginated |
| Bulk writes | A few records at a time, each confirmed | JSONL in, dry run first | Batches of 100 |
| Delete or archive | Not available | Yes, guarded | Yes, guarded |
| Workflows | Not available | List, get, create, update, delete | Create, export, restore |
| Properties | Create only | Create, update, archive | Create |
| Runs headless (CI, scheduled) | No | With a service key | Yes |
Rule of thumb: MCP to look, scripts to change at scale. Reach for the Agent CLI when a job is bulk or administrative and no scripted skill covers it.
| Task shape | Use |
|---|---|
| "Show me 5 contacts the cleanup touched" | MCP |
| "Why is this company in Tier 2?" | MCP |
| "Which open deals has nobody touched this quarter? Show me a few." | MCP |
| "Delete 4,000 no-email contacts with an audit trail" | Scripts (/delete-no-email-contacts) |
| "Create 10 segmentation lists" | Scripts (/build-smart-lists) |
| "Export every workflow to JSON" | Scripts (/workflows-as-code) |
| "Archive these 60 unused properties" | Agent CLI |
What the Server Exposes
HubSpot's remote MCP server lives at https://mcp.hubspot.com and speaks streamable HTTP. It currently offers 32 tools. The ones that matter for CRM administration:
| Tool | What it does | Limit |
|---|---|---|
get_user_details | Your user, account, and per-object read/write access | Run this first to verify the connection |
discover_hubspot_schema | Object types and whether each is readable or writable | |
search_crm_objects | Search and filter records | 5 filter groups of 6 filters; 200 results per page |
get_crm_objects | Fetch records by ID | 100 IDs per call |
query_crm_data | SQL-style aggregate queries | No joins, subqueries, aliases, or association traversal |
search_properties, get_properties | Property definitions and enum values | 5 keywords per search |
search_owners | Owners by name, email, or ID | 100 results |
manage_crm_objects | Create or update records and activities | Shows a change summary and waits for confirmation |
manage_custom_properties | Create custom properties | Create only |
manage_custom_pipelines | Create and manage pipelines | Can edit the default pipeline |
manage_segment | Create segments; add or remove records in static segments | Requires confirmation |
get_marketing_email_analytics | Send statistics, health diagnostics, per-contact engagement | |
tool_guidance | Usage instructions for the other tools | Call before query_crm_data |
The rest cover campaigns, conversations, buyer intent, landing and website pages, blog posts, and AEO.
Readable objects include contacts, companies, deals, tickets, leads, custom objects, segments, activities, and owners. Revenue objects (invoices, orders, line items, products, quotes, subscriptions) are read-only and in beta.
What it cannot do, and what to use instead:
| Cannot | Use instead |
|---|---|
| Delete or archive anything | The scripted skill for that cleanup, or the Agent CLI |
| Read or change workflows | /workflows-as-code, /cleanup-workflows, or the Agent CLI |
| Update or archive a property | /cleanup-properties or the Agent CLI |
| Page through a large result set efficiently | A script. Use query_crm_data when a count or aggregate is all you need |
| Read activities or conversations when Sensitive Data is enabled | The REST API, which is unaffected |
Prerequisites
- A HubSpot user who can create an MCP connector, or an admin who will create one for you
- Claude Code, or the Claude app on a Pro, Max, Team, or Enterprise plan
- Nothing else. This is separate from the service key the scripts use: MCP connects as you, with your HubSpot permissions
Execution Pattern
Stage 1: Plan
- Decide who is connecting. Access is user-scoped, so connect with a user whose permissions match what you want Claude to be able to do. A read-only user gives a read-only connection.
- Check with a Super Admin whether the portal restricts who can connect apps. MCP connections may need approval.
Stage 2: Execute
Option A: the HubSpot connector in the Claude app (no terminal). In Claude's connector settings, add the HubSpot connector and complete the OAuth flow in the browser. HubSpot's guide: knowledge.hubspot.com, "Set up and use the HubSpot connector for Claude". It runs on the same remote server, and HubSpot caps its bulk create and update at 10 records at a time.
Option B: Claude Code. The server does not support dynamic client registration, so a bare claude mcp add cannot aut