HubSpot MCP Setup Guide

Complete guide for setting up the HubSpot MCP server in Cursor for natural language interaction with HubSpot CRM data.

Status

CONFIGURED AND WORKING (as of January 31, 2026)

Prerequisites

HubSpot MCP Auth App - Created in HubSpot Developer portal
Redirect URL configured - http://localhost:3334/oauth/callback

Configuration

The HubSpot MCP is configured in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.hubspot.com/",
        "3334",
        "--static-oauth-client-info",
        "{\"client_id\":\"YOUR_CLIENT_ID\",\"client_secret\":\"YOUR_CLIENT_SECRET\"}",
        "--debug"
      ]
    }
  }
}

Key Configuration Details

Setting	Value	Purpose
`mcp-remote`	npm package	Bridges Cursor to remote OAuth MCP servers
Port `3334`	Fixed OAuth callback port	Must match HubSpot redirect URL
`--static-oauth-client-info`	OAuth credentials	Uses pre-registered HubSpot MCP auth app
`--debug`	Optional	Writes logs to `~/.mcp-auth/`

How It Works

Cursor launches mcp-remote as a local stdio server
mcp-remote handles OAuth flow with HubSpot (PKCE required)
Browser opens for user authorization on first connection
Tokens cached in ~/.mcp-auth/ for subsequent sessions
Proxy established between Cursor and HubSpot MCP server

Available Tools

Tool	Description
`search_crm_objects`	Search contacts, companies, deals, tickets, products, etc.
`get_properties`	Get available properties for any CRM object type
`search_owners`	Find HubSpot owners/users
`search_properties`	Search for specific property definitions

Usage Examples

Once connected, use natural language in Cursor:

"Find all companies named Inteleos in HubSpot"
"Search for Juan Sanchez in HubSpot contacts"
"Show me deals related to Inteleos"
"What properties are available for deals?"
"Who are the HubSpot owners in our account?"

Troubleshooting

OAuth Redirect URL Mismatch

Error: Authorization failed as the redirect URL doesn't match

Fix: Ensure your HubSpot MCP auth app has http://localhost:3334/oauth/callback as a redirect URL.

Clear Cached Auth State

If you encounter authentication issues:

rm -rf ~/.mcp-auth

Then restart Cursor to re-authenticate.

Check Debug Logs

Debug logs are written to:

~/.mcp-auth/mcp-remote-*/[hash]_debug.log

Verify Connection

In Cursor Settings → MCP, the HubSpot server should show a green indicator when connected.

HubSpot MCP Auth App Setup

Go to HubSpot → Development → MCP Auth Apps
Click Create MCP auth app
Configure:
- App name: Your app name (e.g., “Brainforge Cursor MCP”)
- Redirect URL: http://localhost:3334/oauth/callback
Save the Client ID and Client Secret
Add credentials to ~/.cursor/mcp.json

Credentials

Credentials are stored in 1Password:

Item: “HubSpot MCP OAuth Credentials”
Fields: client_id, client_secret

See CREDENTIALS.md for detailed credential management.

Brainforge Knowledge

Explorer

MCP_SETUP