HubSpot MCP Server Setup in 2025 (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 2025, we’re no longer asking if AI belongs in our workflows. We’re asking how to make it truly useful. 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, 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?

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 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: Get the MCP Server code

You’ll start by downloading the server code from GitHub.

Here’s how:

1. Open your Terminal (macOS/Linux) or Command Prompt (Windows).
2. Choose a folder where you want the project to live.
3. Run the following commands:

git clone https://github.com/peakmojo/mcp-hubspot.git

cd mcp-hubspot

This pulls the MCP Server files to your computer and moves you into the project folder.

Step 7: Install the required packages

Next, you’ll install all the tools the server needs to run.

Before you start, make sure you’ve installed Node.js (version 14 or higher). If not, grab it from our previous Step 5 and nodejs.org, install it, and then come back.

Now, inside the mcp-hubspot folder you just cloned, run: npm install

This command reads the package.json file and installs everything listed, just like downloading all the ingredients before you start cooking.

Step 8: Add Your HubSpot access token

This is how the server connects securely to your HubSpot CRM.

Here’s what to do:

1. In the root folder of the project (mcp-hubspot), create a new file named .env
2. Open that file in any text editor and add this line: HUBSPOT_ACCESS_TOKEN=your-access-token
3. Replace your-access-token with the token you got earlier from your HubSpot Private App.

This file keeps your token safe and lets the MCP Server access HubSpot without hardcoding anything.

Pro tip: Never share your .env file publicly. It’s meant to stay private.

Step 9: Start the MCP Server

You’re almost there! Time to launch the server and see it in action. Still inside the project folder, run: npm start

You should see messages in the terminal telling you the server is running. That means it’s live and ready to respond to your AI assistant’s commands.

Want to make sure it’s working? 

Try connecting your assistant and asking it to fetch a contact or update a deal. If it responds correctly, you’re all set.

And….drumroll…congrats! You’ve just set up the HubSpot MCP Server. You’ve got the code, installed the packages, configured your access, and launched the server.

The server’s live. Next, let’s connect your AI assistant so it can start talking to HubSpot.

It only takes a few quick steps.

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 10: Open your AI assistant’s settings

Start by launching your AI assistant platform—no matter if Claude or another tool that supports external APIs.

Head to the Settings or Integrations section.

You’re looking for the place where you can connect custom tools or servers.

It might be labeled “Custom Plugins,” “External Tools,” or “Server Integrations,” depending on the assistant you’re using.

Step 11: Add the MCP Server

Once you’ve found the integrations area, look for an option to add a new server or custom connection.

You’ll need to enter a few key details:

• Server name: Call it something simple and recognizable—like HubSpot MCP Server.
• Server URL: This is where your server is hosted. If you’re running it locally, it’s likely:
  http://localhost:3000. If you’ve deployed it to the cloud, enter the public URL instead.
• Authentication: Use the HubSpot access token you saved earlier. This tells the AI assistant it has permission to interact with your HubSpot data.

Step 12: Configure the connection

Depending on your assistant’s setup, you might be asked to enter some extra configuration details. Here’s what to look out for:

• Startup command: If it asks how to start the server, use: node server.js
• Arguments: If the server requires any startup arguments (most don’t by default), include them here.
• Environment variables: Some assistants let you pass environment variables directly. Add: HUBSPOT_ACCESS_TOKEN=your-access-token. This helps secure communication between the assistant and your MCP Server.

Step 13: Save and test the connection

Once everything’s filled out, hit Save or Connect.

Now it’s time to test it!

Try a simple command in your assistant like:

“Retrieve contact information for Eugene Suslov from Reply.io.”

If everything’s set up right, your assistant will talk to the MCP Server, which will grab the data from HubSpot and return it = all in one smooth interaction.

If it doesn’t work on the first try, double-check:

• That your server is running
• That the access token is correct
• That the URL is reachable from your AI assistant

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.

Let’s continue our journey…

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.

Here’s how to keep your MCP Server fresh:

1. Open your terminal and go to your MCP Server folder: cd mcp-hubspot
2. Check what’s outdated: npm outdated
3. Update everything that needs it: npm update
4. Finally, restart the server: npm start

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.
Server not responding	The assistant can’t connect, or nothing happens when you try a command.	The server might not be running, or the AI can’t reach it.	Start the server. In your terminal, run: npm startStay in the mcp-hubspot folder when doing this.Check the URL Make sure the assistant is pointing to the correct server address. For local setups, this is usually: http://localhost:3000Look out for firewalls. If you’re running this on a cloud server, make sure the right ports are open and your firewall isn’t blocking requests.
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 the HubSpot MCP Server GitHub or HubSpot Developer documentation for detailed examples and updates.

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. 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.

Ready to continue?..

Contribute to the open-source project

Here’s something cool about the MCP Server: it’s not just a tool you use—it’s a tool you can help shape. Since it’s open source, anyone can improve it. That includes you.

Maybe you’ve added a feature that others could use. Maybe you spotted a bug and fixed it. Or maybe you just want to clean up the documentation so it’s easier for the next person. Whatever your skill level, there’s a way to contribute.

Start by heading to the MCP Server GitHub repo. Click Fork to make your own copy of the project. From there, you can:

• Add new features
• Improve error handling
• Fix typos or update the README

Once your changes are tested and working, open a pull request. This tells the maintainers, “Hey, here’s something useful.” They’ll review your code, give feedback if needed, and hopefully merge it into the main project.

And don’t stop there. 

Join the conversation. Ask questions, suggest ideas, or help others troubleshoot in the GitHub discussions. It’s a great way to stay sharp, meet like-minded builders, and contribute to a project that’s making CRM smarter for everyone.

By getting involved, you’re not just improving your own setup—you’re helping create better tools for the whole community.

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…

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 join the waitlist! 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