HubSpot MCP: Setup + Use Cases (2026)

Your HubSpot CRM holds the record of every deal, every contact, and every conversation your company has had. It is the most valuable database most sales teams own. And until recently, the only way to ask it a question was to click through filters, build a view, and read the result yourself.

Claude could not see any of it. You could paste a contact record into a chat and ask about it, but that is not a CRM workflow. That is data entry in reverse. The whole point of a CRM is that the context is already there. The whole point of an AI assistant is to think with you about it. The bridge in the middle did not exist.

Then HubSpot shipped an MCP server. By 2026 there are four different ways to connect Claude to HubSpot, and the official remote one went generally available in April. This guide walks through which path to pick, the five-minute setup for the easy one, what the server can actually do, and where it still needs a human in the loop.

What HubSpot MCP actually does

The Model Context Protocol is an open standard Anthropic released in late 2024. It defines how an AI client talks to an external tool. An MCP server exposes a set of tools, the client calls them mid-conversation, and the results flow back into the model’s reasoning. No copy-paste, no export, no leaving the chat.

For HubSpot, that means Claude can search your contacts, pull a deal’s full history, read the engagement timeline on a company, create a note, and update a record. The CRM becomes a live source the assistant reads from instead of a place you visit when you remember to.

HubSpot now runs an official remote MCP server at mcp.hubspot.com. It went generally available in April 2026, graduating from beta with write access, activity history, and marketing content objects added. The full reference lives in the HubSpot MCP docs.

The launch set is nine tools, covering the CRM objects marketing, sales, and service teams touch every day. Read access reaches contacts, companies, deals, tickets, line items, products, quotes, invoices, and lists, plus activities like calls, emails, meetings, notes, and tasks, plus marketing content like campaigns and landing pages. Write access covers the core records and activities. In practice you do not memorize the tool list. You ask a question and the agent picks the tool.

The 4 ways to connect HubSpot to Claude

This is where most guides skip ahead and pick one path for you. There are four, and the right one depends on whether you want zero setup, full local control, or you are building HubSpot apps.

The clean rule. If you just want to ask your CRM questions, use the remote server or the HubSpot Connector for Claude. They are the same OAuth-backed connection with two front doors. If you have a reason to keep the server process on your own hardware, run the local npm server with a private app token. Only reach for the Developer MCP server if you are writing HubSpot apps, because that one is built for building on the platform, not for daily CRM work.

Most people should start with the remote server and never move. The reason is simple. There is nothing to install, nothing to update, and no token sitting in a config file on your laptop.

Path 1: The remote MCP server (the simple one)

This is the recommended starting point. The connection is hosted by HubSpot and authenticated with OAuth 2.1 with PKCE, so no access token ever lands in your config.

Step 1. Open Claude Desktop settings. Go to Settings, then Connectors, then Add custom connector. This is the same flow you would use for any remote MCP server.

Step 2. Paste the HubSpot MCP URL. Use https://mcp.hubspot.com/anthropic (the path HubSpot publishes for Claude clients, listed in their docs). Give the connector a name you will recognize, like “HubSpot CRM.”

Step 3. Sign in and approve scopes. Claude sends you to HubSpot to authenticate. You log in, pick the account or portal you want connected, and approve the scopes. This is the step that matters most. If you only want the agent to read, do not approve write scopes. You can always widen later.

Step 4. Restart Claude Desktop. Fully quit and reopen. Cmd-Q on macOS, fully close on Windows. A window reload does not pick up a new connector. This trips up roughly half the people who think their setup is broken.

Step 5. Test it. Open a new chat and ask “how many open deals do I have in HubSpot, and what is the total value?” Claude calls the deal tools, returns the numbers, and you are running.

If you would rather skip the connector screen entirely, HubSpot also ships a one-click route. Their HubSpot Connector for Claude wires the same OAuth connection from inside HubSpot, no URL to paste. Same underlying server, friendlier on-ramp.

The trade-off with the remote path is that the connection runs through HubSpot’s servers, which is fine for almost everyone and exactly what you want if you do not run a terminal. If your security team needs the server process on your own infrastructure, use path two.

Path 2: The local npm server (the controlled one)

This is the path for people who want the MCP server running on their own machine. HubSpot publishes an open-source server as the npm package @hubspot/mcp-server. It runs locally and talks to the HubSpot API using a private app access token.

Step 1. Create a private app in HubSpot. In your HubSpot account, go to Settings, then Integrations, then Private Apps. Create one, give it the CRM scopes you need, and copy the access token. Treat the token like a password. It is the only thing standing between a config file and your CRM.

Step 2. Add the server to your Claude Desktop config. Open Settings, then Developer, then Edit Config. That opens claude_desktop_config.json. Drop in the block below, pasting your token into the env value.

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@hubspot/mcp-server"],
      "env": {
        "PRIVATE_APP_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Step 3. Restart Claude Desktop. Same rule as before. Full quit and reopen, not a window reload.

Step 4. Confirm the tools loaded. Ask Claude to “list your HubSpot tools” or just run a read query. If the token scopes are too narrow, you will get a permissions error rather than a broken server, which is a useful signal about what you forgot to grant.

The -y on the npx command is not optional. Without it, npx waits for an interactive install prompt that Claude cannot answer, and the process hangs. This single missing flag is behind a surprising share of “my MCP server will not start” complaints across every community server, not just HubSpot’s.

What you can actually do with it once it is connected

A connected CRM feels underwhelming for five minutes and obvious after a week. Here is the short list of what people actually do with it, grouped by who is asking.

Sales: get deal context without leaving the chat. “What was our last interaction with Acme Corp, and what stage is the deal in?” Claude reads the engagement timeline and the deal record and answers in a sentence. No clicking into the contact, no scrolling the activity feed. The same works for pipeline triage: “summarize every deal in the negotiation stage worth more than $10,000 and flag any with no activity in two weeks.”

Marketing: connect campaigns to pipeline in one question. Because the server reads marketing content and CRM data together, you can ask “which campaigns sourced the contacts that turned into open deals this quarter?” That is a query that normally means stitching two reports together by hand. Huble’s rundown of MCP use cases in HubSpot walks through more of these cross-hub questions.

Operations: catch the data hygiene problems. “Find contacts with no associated company” or “show me deals missing a close date.” The agent runs the search and hands you the list. The boring CRM maintenance that never gets scheduled becomes a thirty-second prompt.

Logging and updates: write back, carefully. With write scopes approved, you can say “log a call with this contact and set a follow-up task for Friday.” The record updates without you opening the form. This is the powerful half and the half to introduce slowly, which is the next section.

“Summarize all deals in the decision-maker-bought-in stage with a value over $5,000, and tell me which ones have gone quiet.”

That single prompt replaces a saved filter, a manual scan, and a mental note to follow up. That is the shape of the win. Not magic, just the report you would have built anyway, asked in one line.

Where HubSpot MCP still needs a human

Honest limits, because a tool you trust blindly is a tool that will eventually embarrass you in front of a customer.

Write access is real access. The remote server can create and update records once you approve the scopes. That is the whole point, and it is also the thing to be careful with. Start read-only. Watch what the agent does when you ask it to draft an update. Approve write scopes only once you have a feel for how it behaves. A wrong bulk update to a pipeline is not a fun afternoon.

It answers, it does not monitor. MCP is request-and-response. You ask, it pulls, it replies. It does not sit in the background watching your CRM and pinging you when a deal goes cold. If you want continuous monitoring, that is a workflow or a HubSpot automation, not the MCP server.

It reads what you can read. The agent inherits the scopes of the connection. It cannot see data the token or the OAuth grant does not cover. That is a feature, not a bug, but it means “Claude could not find that deal” sometimes means “you did not grant that scope,” not “the deal does not exist.”

Big queries get token-heavy. Asking the agent to pull and reason over thousands of records in one go will be slow and can hit context limits. Narrow the query. “Deals in this stage, closing this quarter” beats “tell me about all my deals.” A good prompt scopes the data before the agent ever calls a tool.

The mistakes that break HubSpot MCP setups

The same handful of issues come up again and again.

Reloading instead of restarting. Claude Desktop reads its connector list at full startup only. Reload Window does nothing. Quit fully, reopen, then check.

Approving the wrong scopes. If the agent keeps saying it cannot find or cannot update something, the scopes are usually the cause. Revisit the OAuth grant or the private app permissions and add what is missing. Under-granting is safer than over-granting, so this is the right error to have.

Leaving a private app token in a shared config. If you use the local npm path, that token is live CRM access in plain text. Do not commit claude_desktop_config.json to a repo. Do not paste it in a shared doc. Rotate it if it ever leaks.

Running too many servers at once. Each MCP server is a subprocess with startup and memory cost. Past ten, you feel it. Three to six is the sweet spot, and a CRM server is one of the highest-value slots you can spend.

Expecting it to be a HubSpot replacement. It is a conversational layer on top of HubSpot, not a new HubSpot. The reports, the automations, the dashboards all still live in the app. MCP is the fast lane for questions, not a migration.

Why your saved research belongs next to your CRM

Here is the gap nobody setting up a HubSpot MCP server talks about. Your CRM is only half of what you know about a prospect.

The other half is everything you saved and never filed. The competitor’s launch thread you bookmarked on X. The LinkedIn post from the prospect’s VP of Sales that told you what they actually care about. The Reddit thread where their customers complained about the tool you are replacing. That context shapes how you sell, and none of it is in HubSpot. It is trapped in a bookmarks tab on three different platforms.

HubSpot MCP gives Claude your structured CRM. It does not give Claude the unstructured research you collected along the way. So you end up with an assistant that knows the deal stage but not the story behind it.

This is where a bookmarks MCP earns its slot next to the CRM one. ContextBolt is a Chrome extension that captures what you save on X, Reddit, and LinkedIn, tags each save by topic automatically, and exposes the whole collection through a personal MCP endpoint. The free Basic tier covers 150 bookmarks. Pro at $6 a month adds unlimited saves, encrypted cloud sync, and the MCP endpoint any client can call.

Wire it in the same way you wired HubSpot. Add the custom connector, paste your endpoint, restart. Now Claude reads both halves in one prompt. “Pull the open deal for Acme and anything I have saved about their space” returns the pipeline record and the three threads you bookmarked about their market. The CRM tells you where the deal is. Your bookmarks tell you why it matters. For the full walk-through inside Claude Desktop, see the Claude Desktop integration guide, and for the bigger picture of feeding an agent your own context, Personal AI Context Stack for Claude.

The one opinion worth holding

Most HubSpot MCP guides spend their length on the local npm server, because configuring a token in a JSON file looks like the “real” setup. For almost everyone, that is the wrong default.

The remote server, added through OAuth, covers what people actually do with the integration. It is faster to set up, there is no token to leak, and there is nothing to keep updated. The local path is a genuine option when you have a reason to run the process yourself, and you should know it exists. But choosing it first means taking on the heavier setup before you know whether you need it.

The other thing worth saying plainly. The MCP server you connect matters more than the AI client you connect it to. Claude Desktop, Claude Code, Cursor, and ChatGPT all read the same servers. Wiring up HubSpot once pays off across every client you touch. The same is true for the second half of your context. Connect your CRM, connect your bookmarks, and the assistant finally knows both what the deal is and what you learned chasing it. That is the whole setup. Everything else is detail.