HUBSPOT_MCP_SETUP_STEPS

HubSpot MCP Setup — Step-by-Step

Brainforge brainforge-platform (committed wiring): use stdio + private app token via scripts/hubspot-mcp-stdio.mjs and hubspot-api-setup.md — that path avoids Cursor DCR issues with hosted OAuth. The steps below are for hosted mcp.hubspot.com / mcp-remote setups (e.g. personal ~/.cursor/mcp.json).

Follow these steps to use HubSpot from Cursor (search companies, contacts, deals, etc.) via natural language.

Reference: HubSpot: Integrate with the remote HubSpot MCP server

---

Step 1: Create an MCP auth app in HubSpot

1. Log into HubSpot and go to Settings (gear icon).
2. In the left sidebar, open Development → MCP Auth Apps.
3. Click Create MCP auth app.
4. Fill in:
   • App name: e.g. Brainforge Cursor or Cursor MCP
   • Description: (optional) e.g. “HubSpot in Cursor via MCP”
   • Redirect URL: use exactly:

     http://localhost:3334/oauth/callback

   • Icon: (optional)
5. Click Create.

HubSpot will show the app details page with Client ID and Client secret. Keep this page open (or copy both values somewhere safe).

---

Step 2: Add credentials to Cursor

1. Open your Cursor MCP config file:
   • Mac/Linux: ~/.cursor/mcp.json
   • (Same file Cursor uses for all MCP servers.)
2. Find the "hubspot" block. It should look like this:

   "hubspot": {
     "command": "/Users/roberttseng/.homebrew/bin/npx",
     "args": [
       "-y",
       "mcp-remote",
       "https://mcp.hubspot.com/",
       "3334",
       "--static-oauth-client-info",
       "{\"client_id\":\"PASTE_CLIENT_ID\",\"client_secret\":\"PASTE_CLIENT_SECRET\"}",
       "--debug"
     ]
   }

3. Replace the placeholders:
   • Replace PASTE_CLIENT_ID with your app’s Client ID (from Step 1).
   • Replace PASTE_CLIENT_SECRET with your app’s Client secret (from Step 1).
4. Save the file.

---

Step 3: Restart Cursor and authorize

1. Quit Cursor completely (not just the window), then open it again.
2. The first time you use HubSpot in chat (e.g. “Search HubSpot for company Ilmor”), Cursor will open your browser so you can:
   • Choose your HubSpot account
   • Grant permissions to the app
   • Authorize the connection
3. After you approve, the browser may show a “success” or redirect page; you can close it. Cursor will then be able to talk to HubSpot.

---

Step 4: Test it

In Cursor chat, try:

• “Search HubSpot for companies named Ilmor”
• “List HubSpot deals”
• “Who are the HubSpot owners?”

If you see results (or a prompt to authorize), the setup is working.

---

Troubleshooting

Problem	What to do
“Redirect URL doesn’t match”	In HubSpot, edit the MCP auth app and set Redirect URL to exactly http://localhost:3334/oauth/callback.
HubSpot never asks me to authorize	Restart Cursor again; then send a message that clearly uses HubSpot (e.g. “Search HubSpot for companies”).
Auth errors or stuck	Clear cached auth: run rm -rf ~/.mcp-auth in a terminal, then restart Cursor and go through the browser auth again.

---

What you get

• Read-only access in Cursor to: contacts, companies, deals, tickets, products, orders, and related objects.
• Natural language only (e.g. “Show deals for Inteleos”); no API or config needed in chat.

For writing to HubSpot (e.g. adding notes, updating deals), use the Private App token and the API as in playbook/03-knowledge/engineering/setup/hubspot-api-setup.md.