HubSpot MCP Server Setup in 2026 (Easy Guide)

We both want it. 

Sitting, sipping coffee, getting ready for your day, and you casually tell your AI assistant, “show me the latest updates on our top deals and assign a follow-up task for John.”

No tabs. 

No dropdowns. 

No logging into anything.

Just a quick sentence…and it’s done.

That’s not science fiction. That’s what the HubSpot MCP Server makes possible.

In 2026, we’re no longer asking if AI belongs in our workflows. We’re asking how to make it truly useful, especially for b2b saas lead generation. And that’s where this guide comes in.

The Model Context Protocol Server acts as the missing link between your AI assistant (like Claude) and your HubSpot CRM. It turns conversations into action—updating deals, creating tasks, retrieving contacts from your b2b leads database, and more, all through natural language.

And the best part? You can set it up yourself.

No matter if you’re a tech-savvy marketer, a founder trying to save time, or a curious tinkerer ready to build something cool, this guide will walk you through everything, step by step. 

Just practical instructions, explained like a friend showing you the ropes.

By the end, you won’t just understand the MCP Server.

You’ll have it running—and working—for you. Ready?

Last updated: July 2026 — HubSpot now ships an official MCP server (mcp.hubspot.com, GA since April 2026) and a one-click Claude connector, so the setup steps below cover all three current paths instead of the third-party fork this guide used to point to.

What is the HubSpot MCP server?

The MCP Server (short for Model Context Protocol Server) acts like a middleman—or more precisely, a translator—between your AI assistant Claude and your HubSpot CRM.

Instead of navigating through menus or memorizing workflows, you just ask, and the AI figures out the rest. 

Behind the scenes, the MCP Server is what makes that possible. It listens to the AI’s request, translates it into something HubSpot understands, fetches the right data, and sends it back—fast.

How does it work? Let’s break it down with a simple story.

Say you say to your AI: “Create a new contact for Jane Doe at Generect, add her email, and associate her with the sales team.”

Here’s what happens behind the scenes:

1. You speak (or type) naturally. No commands. Just a request.
2. The AI parses your request and sends it to the MCP Server.
3. The MCP Server translates that into specific HubSpot API calls.
4. HubSpot executes the actions—creates the contact, links it, logs the details.
5. You get confirmation in plain language: “Contact Jane Doe created and linked to HubSpot’s sales team.”

All this happens in real time. You don’t touch your mouse. 

You don’t leave your chat window. Why is this a big deal?

In traditional CRM setups, even simple tasks can take multiple clicks, drop-down selections, and context switching. It’s time-consuming and often frustrating.

The MCP Server changes all that by making your CRM voice-enabled and conversational. That means:

• Less time spent on manual tasks
• Faster access to customer data
• More focus on what really matters—selling, supporting, and growing

And there’s more behind the curtain. The MCP Server includes built-in vector storage and smart caching. That means it remembers context, reduces repeat API calls, and makes your assistant faster and smarter over time.

So instead of hitting rate limits or waiting for laggy responses, your AI just keeps up smoothly and efficiently.

Now that you know what it is, let’s talk about why you’d want it.

Why use the MCP server?

Matter-of-factly, CRMs can be a pain when all you want is to get a simple update or log a quick note. Now imagine having an AI assistant that not only understands what you’re saying but actually does the work inside your HubSpot CRM for you.

That’s exactly what the HubSpot MCP Server makes possible. We’ll lead you through details in a moment…with a huge list of benefits:

The function…	…and how MCP makes it easier
Contact management	You can say, “Add Eugene Suslov from Reply.io as a contact with his email  (verified by an email finder) and phone number,” and the AI handles the entry for you.
Deal updates	Want to move a deal forward? Just say, “Change Reply.io’s deal stage to Proposal Sent.” No need to dig through the pipeline.
Task creation	Had a great call? Say, “Create a follow-up task for next Wednesday with a reminder to send pricing options.”
Predictive forecasts	Get a heads-up on what’s likely to close and what might stall = based on actual trends, not guesses.
Lead scoring	Ask your AI to rank leads by how active or promising they are.
Sentiment analysis	Want to know how your customers feel? The AI can analyze interactions and surface trends in tone and satisfaction.
Connect your tools	Tie your favorite AI model into HubSpot without messy workarounds.
Keep it secure	You control access, so only authorized tasks and data get touched.
Use natural language	Just say what you want. The AI understands and handles it.

The end result? A streamlined workflow that cuts out manual effort, reduces tool-hopping, and makes your CRM work the way you do.

Before we dive in, let’s get your tools ready…a little prep now will save you a lot of trouble later.

What do you need before starting?

Think of this like prepping your workspace before assembling furniture—you’ll save a ton of time and avoid headaches later.

Here’s what you’ll need and how to get it.

Step 1: Register a HubSpot account

First things first: you need an active HubSpot accoun:.

• If you already have one, great—you’re ready to move on. 
• If not, head over to hubspot.com and sign up. A free CRM account works for testing, but for real AI integration, you might need more advanced features depending on your use case.

Step 2: Create a private app in HubSpot

This is how the MCP Server talks to your HubSpot data. Don’t worry—it’s simple.

Here’s how to create it:

1. Log in to your HubSpot account.
2. Go to Settings (top right).
3. In the left sidebar, click Account Setup → Integrations → Private Apps.
4. Click Create a private app.
5. Give it a name and short description (e.g., “MCP HubSpot Integration”).
6. Choose the scopes—these define what your app can access (more on that below).
7. Hit Create app.

Once that’s done…

Step 3: Save your access token

Right after creating your private app, HubSpot gives you a long string of characters—that’s your access token.

Important → copy it right away and store it somewhere safe. You won’t be able to see it again. You’ll use this token so the MCP Server can make secure API calls on your behalf.

Step 4: Set the right permissions (scopes)

When you set up your private app, you’ll need to choose which parts of HubSpot your AI can interact with.

Start with these commonly used scopes:

• crm.objects.contacts.read and crm.objects.contacts.write
• crm.objects.companies.read and crm.objects.companies.write
• crm.objects.deals.read and crm.objects.deals.write

These give your AI access to view and update contacts, companies, and deals.

Need more? You can find the full list of scopes in the HubSpot Developers Scope Guide.

Step 5: Install Node.js

The MCP Server runs on Node.js, so you’ll need that installed on your computer before anything else.

Here’s how:

1. Go to the Node.js official site
2. Download the LTS version (Long Term Support)—make sure it’s version 14 or higher
3. Run the installer and follow the prompts based on your system (Windows, macOS, Linux)

Need help with installation? There are tons of helpful video tutorials online, especially if you’re on Windows.

Once you’ve got:

• A HubSpot account
• A private app with the right scopes
• Your access token saved
• Node.js installed…

…you’re ready to start setting up the MCP Server. But we need your attention for a moment…

How to set up the MCP server?

Setting up the HubSpot MCP Server might sound technical, but don’t worry—you don’t need to be a developer to get it working. If you’ve ever followed a recipe or assembled a piece of IKEA furniture, you can handle this. 

Let’s walk through it step by step.

Step 6: Pick your setup path

You don’t need to clone a random GitHub repo anymore. HubSpot now ships an official MCP integration three ways — pick the one that fits how you work.

• Fastest — HubSpot connector for Claude: a one-click connector in Claude’s own Connectors marketplace. No install, no config file, no token to manage.
• Most flexible — official remote MCP server (mcp.hubspot.com, GA since April 2026): OAuth-based, works with Claude, ChatGPT, Cursor, or any MCP-aware client, nothing running on your machine.
• Self-hosted — official @hubspot/mcp-server npm package: runs locally via npx, uses your private app token. Best if you want the process on your own machine.

All three reach the same HubSpot data — none is “more official” than another. Here’s how to set up each.

Option A: HubSpot connector for Claude (no install)

This is what HubSpot recommends for most Claude users — it skips the private app token entirely.

1. In Claude, click your profile icon → Settings → Connectors.
2. Click Browse connectors, open the Web tab, and select HubSpot.
3. Click Add to your team, then back on the connectors page click Connect next to HubSpot.
4. Log in to the HubSpot account you want connected and approve the requested permissions.
5. Need teammates to use it too? In HubSpot, go to Settings → Integrations → Connected Apps → HubSpot connector for Claude and click Give users access.

No Node.js, no terminal, no .env file. Skip straight to “How to connect your AI assistant” below once it’s connected.

Option B: official remote MCP server (mcp.hubspot.com)

Use this if you’re on a Claude plan that supports custom connectors, or you want the same HubSpot MCP server working across Claude, Cursor, or another MCP client.

1. In Claude Desktop: Settings → Connectors → Add custom connector.
2. Paste the URL HubSpot publishes for MCP clients — https://mcp.hubspot.com — and name it something you’ll recognize, like “HubSpot CRM.”
3. Claude redirects you to HubSpot to sign in and approve scopes. Start read-only if you’re unsure — you can widen access later.
4. Fully quit and reopen Claude Desktop (a window reload isn’t enough — this trips up about half the people who think their setup is broken).
5. Using Claude Code instead? Run: claude mcp add –transport http hubspot https://mcp.hubspot.com, then type /mcp inside a session to authenticate.

Option C: self-hosted @hubspot/mcp-server (npm package)

Want the process running on your own machine? Use HubSpot’s official npm package instead of the third-party forks that used to be the only option. You’ll need the private app token and Node.js from the prerequisites above (Steps 1–5).

Open your AI client’s MCP config file — for Claude Desktop that’s claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) — and add this block:

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

Replace your-access-token with the token from Step 3, save the file, then fully quit and reopen Claude Desktop. npx downloads and runs the package on demand — no git clone, no npm install, no npm start, and no server URL or port to manage.

For Claude Code, add the same block to .claude/settings.json or ~/.claude.json — it connects automatically on your next session.

Any of the three options gets your AI assistant talking to HubSpot. Next, let’s confirm the connection is actually live.

How to connect your AI assistant?

Now that your HubSpot MCP Server is up and running, it’s time to connect your AI assistant. This is where the magic happens—your assistant will finally be able to talk to your HubSpot CRM and actually do things with it.

Let’s go through it together, step by step.

Step 7: Confirm the tools loaded

Whichever path you chose — native connector, remote server, or self-hosted package — confirm it’s actually working before you rely on it.

Open a new chat and check that HubSpot shows up as an active tool source (in Claude: the search-and-tools icon in the chat box, or just ask “list your HubSpot tools”).

Nothing showing up? The most common cause is a reload instead of a full restart — quit the app completely (Cmd-Q on macOS, not just closing the window) and reopen it.

Step 8: Run a real test query

Ask something that forces a live API call instead of a guess, for example:

“How many open deals do I have in HubSpot, and what’s the total value?”

If your assistant calls the HubSpot tools and returns real numbers from your CRM, you’re set. If it answers from general knowledge instead — or says it can’t access HubSpot — the connection isn’t live yet. Recheck the option-specific step above (token, scopes, or restart) before moving on.

That’s it — you’ve just given your AI assistant superpowers. From now on, it can manage your CRM through natural conversation. No menus, no clicking around—just results.

With everything connected, let’s make sure it runs smoothly. Here’s how to test, monitor, and keep things working well. Yet, just a moment of your time…

How to use the MCP server effectively?

Now that your HubSpot MCP Server is up and running, let’s make sure you’re getting the most out of it.

Think of this as fine-tuning your setup—like making sure a new tool is sharp, aligned, and ready for everyday use.

These quick tips will help you run smoother, avoid issues, and stay in control.

Start in a safe testing space (Sandbox)

Before making changes in your live HubSpot account, test everything in a sandbox environment.

This gives you a safe space to try commands, check permissions, and experiment—without risking real customer data.

Here’s how to set one up:

1. Log into your HubSpot account.
2. Go to Settings → Account Setup → Sandboxes.
3. Click Build standard sandbox.
4. Follow the prompts, like name it, choose what data or assets to sync, and hit confirm.

Once it’s ready, you can connect your MCP Server and AI assistant to this test version of HubSpot. It works just like the real thing, but nothing you do here will impact your actual CRM.

Using a sandbox is the best way to catch small issues before they become big ones.

Keep an eye on server logs

Server logs are like a behind-the-scenes view of what’s going on. If something breaks, this is where you’ll find out why.

Here’s how to monitor them:

• If you’re running the server locally, your terminal will show real-time logs as you use it.
• Look out for errors, failed requests, or timeouts—these can tell you if something needs fixing.
• For advanced setups, you can plug logs into tools like Loggly, Papertrail, or Datadog to get alerts when something unusual happens.

Checking your logs regularly helps you stay ahead of problems. It’s like checking the oil in your car—easy to forget, but super helpful in the long run.

Keep everything up to date

Technology moves fast. Updates often bring speed boosts, new features, and better security.

How you stay current depends on your setup:

• Native connector or remote server (Options A/B): nothing to do — HubSpot updates the hosted server on its end.
• Self-hosted npm package (Option C): npx already fetches the latest published version each time it starts, so a full restart of your AI client is usually enough. To pin or clear a cached version: npx clear-npx-cache, then restart.

By staying up to date, you’ll avoid bugs and make sure your server keeps working smoothly with HubSpot and your AI tools.

Using the MCP Server effectively means more than just turning it on—it’s about maintaining it, testing safely, and staying alert to anything that might go wrong.

Here’s your quick checklist:

• Test in a sandbox before going live
• Monitor logs for real-time feedback
• Keep your server and packages updated regularly

Sometimes things break—that’s normal. 

Here’s how to fix the most common issues fast.

What are common issues and solutions?

So you’ve got your HubSpot MCP Server set up, but something’s not working quite right? Don’t stress…it happens to all of us. The good news is, most issues are easy to fix once you know where to look.

Let’s walk through some common problems and how to solve them fast, so your AI assistant can get back to doing what it does best.

The issue	What it looks like	What’s going on	How to fix it
Authentication errors	Your AI assistant says something like “unauthorized” or “authentication failed.”	The server can’t confirm your identity—usually because the token is missing, expired, or incorrect.	Check your token. Open your .env file and make sure the token matches the one from your HubSpot private app.Token expired or revoked? Log in to HubSpot, generate a new token from your Private App settings, and replace the old one in .env.Using email services (SMTP/IMAP)? You may need an app-specific password—check your provider’s settings if you’re connecting to email.
Permission problems	Your assistant says it can’t read or write certain data in HubSpot.	Your token or HubSpot user might not have permission to do what you’re asking.	Review scopes. Go to your Private App settings in HubSpot and double-check the scopes. At minimum, you’ll need ones like: crm.objects.contacts.read OR crm.objects.contacts.writeCheck user permissions. Make sure the HubSpot user linked to your token has the right access level—especially for contacts, deals, and companies.
No response / tools not loading	The assistant can’t connect, or nothing happens when you try a command.	Self-hosted (Option C): the npx process isn’t running or the token is wrong. Connector/remote (Options A/B): the app wasn’t fully restarted after connecting.	Self-hosted: check that your MCP config file has the correct command/args/token, then fully quit and reopen your AI client — it relaunches the npx process for you, there’s no server to start manually. Connector/remote: fully quit (not just close the window) and reopen the app, then re-check the connector shows as connected in Settings → Connectors.
Invalid configuration	Strange errors, unexpected behavior, or the assistant just doesn’t seem to understand what it should do.	Something in your setup may be misconfigured—either in the server or AI assistant settings.	Review your .env file. Make sure all required variables are filled in correctly. A typo or missing line can break things. Check the assistant’s config. Revisit the integration settings in your AI tool. Double-check the server URL, token, and startup commands.

If you’ve gone through all that and things still aren’t working, don’t give up—there are more ways to troubleshoot:

• Check the logs → your terminal or hosting platform will show live logs when the server runs. Look for error messages—they’re usually specific and helpful.
• Ask the community → the HubSpot Community is full of smart folks who’ve likely seen your issue before.
• Read the docs → visit HubSpot’s official MCP documentation for the current tool list, OAuth scopes, and rate-limit behavior.

Solving problems is part of the process—it’s how you learn what’s really going on under the hood. Once you’ve fixed a few hiccups, you’ll feel way more confident managing and customizing your MCP setup.

Want to do more? You can.

Here’s how to customize the server and make it fit your needs even better.

How to extend the MCP server?

Once your HubSpot MCP Server is running smoothly, you might start wondering: “Can I make it do more?”

The answer is yes—absolutely.

No matter if you want to customize it for your team’s workflow, plug into more HubSpot APIs, or give back to the community, the MCP Server is designed to be extended.

Here’s how to do it effectively.

Build custom tools for your business

Every business runs a little differently, and sometimes the out-of-the-box MCP Server just isn’t enough. 

Maybe you need your assistant to assign leads to reps based on region, or to generate a custom summary after every deal closes. Instead of waiting for someone else to build that feature, you can create it yourself. 

Start by spotting the manual tasks in your daily routine that your AI could handle better. 

Once you’ve got a clear use case, dive into the MCP Server code and add a new endpoint—something like /api/assign-lead. This is where you’ll write the logic in Node.js to interact with HubSpot: pull the data, process it, and send the response back. Think of it like creating a shortcut tailored to your exact workflow. 

Once the endpoint’s in place, test it thoroughly using a tool like Postman or directly through your assistant. Make sure it behaves as expected and doesn’t interfere with anything else. With a few tweaks, you’ve just made your CRM smarter and more aligned with how your team actually works.

Adding your own tools makes the server feel like it was built just for you, which, now, it kind of is.

Integrate more HubSpot APIs

The default MCP Server focuses on CRM basics like contacts, deals, and companies—but HubSpot has so much more to offer: emails, engagements, marketing events, and more.

If your use case goes beyond the basics, here’s how to expand:

1. Explore HubSpot’s API docs → visit developers.hubspot.com and browse what’s available, or connect an automated lead generation system to enrich your data.. Think beyond CRM—consider Marketing, CMS, or Conversations APIs.
2. Add new functions → extend the MCP Server HubSpot-based to call these new APIs. Create additional endpoints that handle these interactions.
3. Update your authentication → make sure your access token includes scopes for the new APIs you’re calling.
4. Test your MCP-HubSpot integration → check that everything runs smoothly from your AI assistant. A simple call like “Get latest marketing email stats” should trigger the right response.

By tapping into more of what HubSpot offers, your AI assistant can become a true all-in-one CRM interface. And we have one more thing to share with you…

Ready to continue?..

When to build on a community fork instead

The official options above (connector, remote server, npm package) cover the vast majority of use cases now — that’s a shift from a year ago, when a third-party fork was the only way in.

Reach for an open-source community server only if you need something the official tools genuinely don’t expose yet — a custom endpoint tied to your own workflow, for example. Check HubSpot’s MCP documentation first for the current tool list and scopes; if what you need is missing, search GitHub for actively maintained forks rather than defaulting to whichever one an older guide linked to, since unmaintained forks fall behind HubSpot’s API changes fast.

For anything short of that, building your own endpoint is more maintenance than most teams want to take on — you’re now the one keeping it in sync with HubSpot’s API.

You made it! From setup to advanced tips, you now have a smart CRM that works with your AI assistant.

Let’s put it to good use…

Frequently Asked Questions

Wrapping up

Think back to where you started—just an idea: “What if I could talk to my CRM like I talk to a teammate?”

Now look at you. You’ve walked through every step, from setting up the HubSpot MCP Server to connecting your AI assistant and tailoring it to your business needs. You’ve turned that idea into a fully functioning system—one that listens, acts, and gets things done with a simple sentence.

No more digging through menus. No more repetitive clicking. No more bouncing between tools.

Instead, you’ve built something smarter. 

Faster. 

Yours.

Along the way, you didn’t just install software. You:

• Gave your CRM a voice
• Solved real problems with simple commands
• Learned how to fix issues without panic
• Customized the server to match how you work
• And maybe (just maybe) started thinking like a builder, not just a user

And the best part? This is just the beginning.

There’s still more you can do—more APIs to tap into, more workflows to automate, more moments to save. You’ve got the tools. You’ve got the know-how. Now, it’s about using it to make your day-to-day easier and your team even stronger.

So, what’s next?

Maybe you fine-tune your setup. Maybe you consider using a tool that changes how your team handles leads, like Generect? Welcome to try Generect MCP! Or maybe you contribute back to the open-source community and help someone else get started, just like you did.

Wherever you go from here, remember: you don’t need to be a developer to build powerful things. You just need a guide, a bit of curiosity, and the confidence to try.

You’ve got all three.

Now go build something amazing