How to connect a HubSpot MCP to Cursor (4 steps)

HubSpot's objects aren't self-explanatory.

Contacts, companies, deals, and tickets each carry dozens of properties whose internal names don't match their UI labels.

To write correct code against any of it, you need to see a real object first, and that means leaving the editor for HubSpot's API explorer and carrying the answer back in a browser tab.

To help your developers query HubSpot data without leaving Cursor, we'll show you how to connect HubSpot with Merge Agent Handler's HubSpot MCP server.

How it works

Merge Agent Handler connects Cursor to HubSpot's CRM API through the Merge CLI.

You install the CLI, authenticate once, and run a single setup command from your project root.

That command writes a ## Merge CLI section to your project's .cursorrules file, which tells Cursor's agent when to call merge search-tools and merge execute-tool to reach third-party services.

Once connected, Merge manages your HubSpot OAuth token storage and refresh on your behalf, so no credential state lives in your local environment.

Related: How to use the HubSpot MCP in Claude Code

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Cursor installed
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A HubSpot account with admin or API access

If you want to connect Merge Agent Handler's HubSpot MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Add the Merge CLI to your environment with pipx: pipx install merge-api

Confirm the installation succeeded: merge --version

2. Log in to Merge

Connect the CLI to your Merge Agent Handler account: merge login

This links the CLI to your account so Merge can make authorized requests against HubSpot on your behalf.

3. Connect the CLI to Cursor

Run the following from the root of the project where you want to use Merge tools:

merge setup cursor

This writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services. The command is idempotent, so it's safe to re-run if you need to reset.

Related: The steps for integrating a HubSpot MCP with Codex

4. Authenticate HubSpot

Open a Cursor chat in your project and try a query like:

Fetch one of our deals and list every property on it with its internal name and type, so I can model the deal object correctly in my integration code.

The first time you invoke a HubSpot tool, a Magic Link will appear to complete connector authentication.

{{this-blog-only-cta}}

HubSpot MCP FAQ

In case you have more questions on setting up and using the HubSpot MCP in Cursor, we've addressed several more commonly-asked questions below.

What can you do once the HubSpot MCP is connected to Cursor?

With HubSpot connected, Cursor can:

• Inspect a real object before writing your model: retrieve a contact, company, or deal to see the exact properties it returns, so your types match the API instead of the UI labels

• Resolve internal property names: pull an object's properties to get the real internal names (like dealstage or hs_object_id) your code has to reference, not the display names

• Fetch pipeline and deal-stage IDs: read a pipeline definition to get the stage IDs your stage-transition logic needs, since the API expects IDs rather than the labels shown in HubSpot

• Inspect association structure: retrieve an object with its associations to see how related records and association type IDs come back before you write traversal code

• Validate pagination on real data: run a search that returns many records to see how paging.next.after is returned before you implement your pagination loop

Why use Merge Agent Handler vs. a self-hosted HubSpot MCP server?

You can self-host a HubSpot MCP server using open-source packages that wrap the HubSpot API directly.

For a solo developer working against their own portal, that setup works: create a private app, generate a token, stand up the server, and point Cursor at it.

The overhead compounds at the team level.

HubSpot auth means managing private app tokens or OAuth credentials, keeping them fresh, and making sure they survive process restarts. If several developers need HubSpot access through Cursor, each one manages their own token or they get shared in ways that are hard to audit and revoke cleanly.

Merge Agent Handler centralizes authentication and adds a control layer on top.

You define which HubSpot operations each agent is allowed to call, Merge enforces those boundaries, and every tool call is logged with a full audit trail that includes the input and output.

For teams where HubSpot holds customer records, pipeline data, and revenue numbers, that combination of access scoping and observability is what makes a production deployment defensible rather than just functional.

Why connect HubSpot to Cursor?

Developers writing HubSpot integrations have to understand the CRM's data model before they can write correct code against it.

HubSpot represents records as objects with typed properties, connects them through typed associations, and models deal progress as pipeline stage IDs. That structure is documented, but reading the docs isn't the same as seeing a real object from the portal your integration will run against.

With the HubSpot MCP connected, Cursor can pull real HubSpot data directly in the chat panel. You can fetch a deal while writing the parser that will process it, retrieve a pipeline while writing the stage logic that maps to it, or resolve real property names while writing the calls that use them.

The data your code operates on and the code itself live in the same session, which removes the round-trip to the API explorer or a separate test script.

Can I use Merge's HubSpot MCP with my employees?

Yes, Merge for Workforce is built to help organizations provision, secure, and govern how employees connect AI to systems like HubSpot.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which employees can read or edit HubSpot records by role or team

• DLP and policy enforcement on tool calls, so admins can block queries that would return sensitive customer or revenue data before results reach the employee's AI session

• User-level audit logging so security and IT teams can review which records were viewed, created, or updated, by which employee identity, and when

In practice, employees can use the HubSpot MCP to look up contacts, summarize pipelines, update records, and more, while IT keeps centralized control over which objects and operations each identity can reach.