HubSpot MCP Server Setup for Cursor IDE (2026)

If you're building integrations with HubSpot — or just need CRM context while you work — connecting HubSpot to Cursor via MCP means your AI can pull contact records, deal data, and pipeline information directly into your coding session.

This is useful for developers building HubSpot integrations, writing custom workflows, or debugging API-connected features where you need real CRM data without switching tabs.

What You Can Do with HubSpot + Cursor MCP

Once connected, you can ask Cursor things like:

"Find the contact record for john@example.com"

"List all open deals in the Enterprise pipeline"

"What custom properties exist on the Contact object?"

"Show me the schema for the Deals API"

"Pull the last 10 form submissions from the Marketing Forms page"

This is particularly useful when writing HubSpot API integrations — instead of consulting docs and testing in Postman, you can query live data and generate code in the same context window.

Prerequisites

Cursor IDE v0.40+

Node.js 18+

HubSpot account with API access

HubSpot Private App token (recommended) or API key

Step 1: Create a HubSpot Private App Token

HubSpot's recommended auth method for API access is Private Apps (not the legacy API key).

1. Go to HubSpot Settings → Integrations → Private Apps
2. Click Create a private app
3. Name it (e.g., "Cursor MCP")
4. Under Scopes, select what you need:

crm.objects.contacts.read

crm.objects.deals.read

crm.objects.companies.read

crm.schemas.contacts.read

forms (if you need form submission data)

5. Click Create app and copy the access token

Keep this token — you won't be able to see it again after closing the dialog.

Step 2: Install the HubSpot MCP Server

The community-maintained HubSpot MCP server covers core CRM objects and properties:

npm install -g @hubspot/mcp-server

Or use it directly via npx (no install required):

npx @hubspot/mcp-server --help

Step 3: Add to Your Cursor mcp.json

Open ~/.cursor/mcp.json (macOS/Linux) or C:\Users\\.cursor\mcp.json (Windows) and add:

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your_private_app_token_here"
      }
    }
  }
}

Replace your_private_app_token_here with the token you copied in Step 1.

On Windows, use the full path to npx if it doesn't load:

"command": "C:\\Program Files\\nodejs\\npx.cmd"

Step 4: Restart Cursor and Verify

Quit Cursor completely and reopen it. Check it loaded:

macOS/Linux: Open Terminal, run cursor --open-devtools

In Cursor: View → Output → MCP

You should see the HubSpot server listed without errors. Then test in Cursor chat:

List all contacts added in the last 7 days

Practical Use Cases

Building a HubSpot Integration

I'm building a webhook handler for HubSpot deal stage changes. 
What properties are available on the Deal object, and what does 
the webhook payload look like for a deal stage update?

Cursor will pull the actual Deal schema from your HubSpot account and help you write the handler with real field names — not guessed ones from outdated docs.

Debugging a CRM Sync

Find the contact record for the email address test@acme.com 
and show me all their associated deals and the last activity date

Instead of logging into HubSpot and clicking through the UI, you get the data directly in your code editor where you're working.

Writing HubSpot API Code

Write a Python function that fetches all contacts with the 
lifecycle_stage = 'customer' and exports their email, first name, 
and last modified date to a CSV

With live schema access, Cursor knows the exact property names and API structure — the generated code is accurate, not generic.

Understanding Custom Properties

What custom properties exist on the Contact object in our HubSpot account?

This is especially useful when you're new to a client's HubSpot setup and need to understand their data model before writing any integration code.

Available HubSpot MCP Tools

The standard HubSpot MCP server exposes:

hubspot_get_contact — Retrieve a contact by ID or email

hubspot_search_contacts — Search contacts with filters

hubspot_get_deal — Retrieve a deal by ID

hubspot_list_deals — List deals with pipeline/stage filters

hubspot_get_company — Retrieve a company by ID

hubspot_get_object_schema — Get properties for any CRM object type

hubspot_list_properties — List all properties on a given object

Check the server's documentation for the full list — it expands as HubSpot's API coverage grows.

Troubleshooting

"401 Unauthorized"
Your access token is invalid or expired. Regenerate it from HubSpot → Settings → Private Apps. Make sure the token is pasted correctly with no spaces or line breaks.

"403 Forbidden"
Your private app doesn't have the required scopes. Go back to the private app settings in HubSpot and add the missing permissions.

Server loads but returns no data
Verify your HubSpot portal has data in the objects you're querying. Test with a simple request: List 5 contacts from our HubSpot account.

"Cannot find package @hubspot/mcp-server"
The package name may have changed. Check npm for the current package: npm search hubspot mcp. The community-maintained alternatives also work well.

---

Salesforce MCP Server for Cursor IDE (2026)

Notion MCP Server for Cursor IDE (2026)

Best MCP Servers for Developers (2026)

HubSpot MCP Server in Cursor IDE: Query CRM Data While You Code (2026)