Brainforge Knowledge

setup

3 min read

HubSpot MCP Server Setup Guide

This guide walks you through setting up the HubSpot MCP server for natural language interaction with HubSpot CRM data in Cursor.

Overview

The HubSpot MCP server enables read-only access to HubSpot CRM objects (deals, contacts, companies, etc.) through natural language queries in Cursor. For write operations, use the HubSpot API service.

Prerequisites

  • HubSpot account with admin access
  • Cursor IDE
  • MCP Inspector (optional, for testing)

Step 1: Create HubSpot MCP Auth App

  1. Log in to your HubSpot account
  2. Navigate to Settings → Integrations → Private Apps (or Development → MCP Auth Apps)
  3. Click Create MCP auth app (or Create app)
  4. Fill in app details:
    • App name: Brainforge HubSpot MCP
    • Description: MCP integration for natural language HubSpot queries
    • Redirect URL:
      • For MCP Inspector testing: http://localhost:6274/oauth/callback/debug
      • For production: Your MCP client’s callback URL
  5. Click Create

Step 2: Get App Credentials

After creating the app, you’ll see:

  • Client ID: Copy this value
  • Client Secret: Copy this value (keep it secure!)

Step 3: Configure Cursor MCP Client

Option A: Using MCP Inspector (Testing)

  1. Run the MCP Inspector locally
  2. In the browser, configure:
    • Transport Type: Streamable HTTP
    • URL: https://mcp.hubspot.com/
    • Client ID: Your app’s Client ID
    • Client Secret: Your app’s Client Secret
  3. Click Open Auth Settings → Guided OAuth Flow
  4. Follow the OAuth flow to authorize the app
  5. Test queries: “List all deals” or “Get user details”

Option B: Configure in Cursor Settings

Add to your Cursor MCP configuration (location varies by setup):

{
  "mcpServers": {
    "hubspot": {
      "url": "https://mcp.hubspot.com/",
      "transport": "http",
      "auth": {
        "type": "oauth",
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
        "redirectUri": "YOUR_REDIRECT_URI"
      }
    }
  }
}

Step 4: Test the Connection

Once configured, test with natural language queries in Cursor:

  • “Show me all deals”
  • “What deals are in the ‘Qualified To Buy’ stage?”
  • “Get contact details for Juan Sanchez”
  • “List all companies”

OAuth Flow Details

The HubSpot MCP server uses OAuth 2.1 with PKCE (Proof Key for Code Exchange):

  1. Authorization Request: Client generates code verifier and challenge
  2. User Authorization: User authorizes app in HubSpot
  3. Token Exchange: Client exchanges authorization code for access token
  4. API Requests: Client uses access token for HubSpot API calls

Note: PKCE is required for HubSpot MCP authentication. Most MCP clients (like MCP Inspector) handle PKCE automatically.

Available MCP Tools

The HubSpot MCP server provides read-only access to:

  • Deals: Search and retrieve deal information
  • Contacts: Get contact details and properties
  • Companies: Retrieve company information
  • Tickets: Access support ticket data
  • Products: Get product information
  • Orders: Retrieve order data
  • Line Items: Access line item details
  • Invoices: Get invoice information
  • Quotes: Retrieve quote data
  • Subscriptions: Access subscription information

Limitations

  • Read-only: MCP server provides read access only
  • Write operations: Use the HubSpot API service (api-service/) for create/update operations
  • Rate limits: HubSpot OAuth apps are limited to 100 requests per 10 seconds

Troubleshooting

”Invalid client credentials”

  • Verify Client ID and Client Secret are correct
  • Ensure redirect URL matches exactly (including protocol and port)

“Authorization failed”

  • Check that PKCE is enabled in your MCP client
  • Verify redirect URL is configured correctly in HubSpot app settings

”Rate limit exceeded”

  • HubSpot limits OAuth apps to 100 requests per 10 seconds
  • Implement rate limiting or use the API service with retry logic

Next Steps

  • Set up the HubSpot API service for write operations: See ../api-service/README.md
  • Configure Linear ticket enrichment: See ../enrichment/README.md

References

Graph View