hubspot-mcp-server

A Model Context Protocol (MCP) server for the HubSpot CRM API — works both locally via Claude Desktop (stdio) and remotely via claude.ai (HTTP + bearer token).

---

Tools

Domain	Tools
Contacts	hubspot_get_contact, hubspot_list_contacts, hubspot_create_contact, hubspot_update_contact, hubspot_delete_contact
Companies	hubspot_get_company, hubspot_list_companies, hubspot_create_company, hubspot_update_company, hubspot_delete_company
Deals	hubspot_get_deal, hubspot_list_deals, hubspot_create_deal, hubspot_update_deal, hubspot_delete_deal
Search & Assoc.	hubspot_search, hubspot_associate_records, hubspot_list_associations

---

Setup

1. Create a HubSpot Private App

1. Go to HubSpot → Settings → Integrations → Private Apps
2. Click Create a private app, then under Scopes add:
   • crm.objects.contacts.read + write
   • crm.objects.companies.read + write
   • crm.objects.deals.read + write
3. Copy the generated Access Token

2. Install & Build

npm install
npm run build

---

Option A — Claude Desktop (local, stdio)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["/absolute/path/to/hubspot-mcp-server/dist/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-your-token-here"
      }
    }
  }
}

Restart Claude Desktop — the tools will appear automatically.

---

Option B — claude.ai browser (remote, HTTP via Render)

Step 1 — Deploy to Render

1. Push this repo to GitHub

2. Go to render.com → New → Web Service

3. Connect your GitHub repo

4. Render detects render.yaml automatically. Set these Environment Variables in the dashboard:

   Key	Value
   HUBSPOT_ACCESS_TOKEN	Your HubSpot private app token
   MCP_API_KEY	A strong random secret you generate (e.g. openssl rand -hex 32)
   TRANSPORT	http

5. Deploy. Your URL will be: https://hubspot-mcp-server.onrender.com

Free tier note: Render's free tier spins down after 15 minutes of inactivity. The first request after spin-down takes ~30 seconds. Upgrade to Starter ($7/mo) to keep it always-on.

Step 2 — Connect in claude.ai

1. Go to claude.ai → Settings → Integrations
2. Click Add MCP Server
3. Fill in:
   • URL: https://hubspot-mcp-server.onrender.com/mcp
   • Header name: Authorization
   • Header value: Bearer <your MCP_API_KEY>
4. Click Connect — the 15 HubSpot tools will appear in your next conversation

---

Environment Variables

Variable	Required	Description
HUBSPOT_ACCESS_TOKEN	✅	HubSpot private app token
MCP_API_KEY	✅ (HTTP mode)	Bearer token that Claude.ai sends to authenticate
TRANSPORT	No	stdio (default) or http
PORT	No	HTTP port, default 3000 (Render sets this automatically)

---

Generate a secure MCP_API_KEY

openssl rand -hex 32

Copy the output into Render's environment variables and into the claude.ai header value field.

---

Local HTTP testing

HUBSPOT_ACCESS_TOKEN=pat-xxx MCP_API_KEY=mysecret TRANSPORT=http node dist/index.js

# Test auth
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer mysecret" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Health check (no auth)
curl http://localhost:3000/health