hubspot-mcp

Let Claude and other AI agents query your HubSpot CRM in natural language.

hubspot-mcp is a Model Context Protocol server that exposes your HubSpot CRM — contacts, deals, companies, and quotes — to AI agents. Ask "What deals are in the proposal stage?" or "Find the contact for acme.com" and the agent answers from live HubSpot data.

Read-only and safe by default. The server only uses read scopes; it cannot modify your CRM.

Features

• 🔎 Search contacts, deals, companies, and quotes

• 📇 Fetch full details for any record by id (with associations)

• 🧭 List deal pipelines and stages so the agent knows valid filters

• 🔒 Read-only by design — no write scopes requested or used

• 🐍 Pure Python, built on the official MCP SDK (FastMCP)

Related MCP server: HubSpot MCP Server

Tools

Install

Install directly from GitHub:

pip install git+https://github.com/MBAD753/hubspot-mcp
# or, isolated:
pipx install git+https://github.com/MBAD753/hubspot-mcp

A PyPI release (pip install hubspot-mcp) is planned — see the roadmap below.

Setup

1. In HubSpot, go to Settings → Integrations → Private Apps → Create a private app.

2. Grant read-only scopes: crm.objects.contacts.read, crm.objects.deals.read, crm.objects.companies.read, crm.objects.quotes.read.

3. Copy the access token and set it in your environment:

export HUBSPOT_ACCESS_TOKEN="pat-na1-xxxx..."

Tip: Use a free HubSpot developer/test account while evaluating — never point a tool at a production account until you trust it.

Use with Claude Code

Register the server (user scope makes it available in every project):

claude mcp add hubspot --scope user \
  --env HUBSPOT_ACCESS_TOKEN=pat-naX-xxxx... \
  -- hubspot-mcp

Or add it directly to your ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "hubspot": {
      "type": "stdio",
      "command": "hubspot-mcp",
      "env": { "HUBSPOT_ACCESS_TOKEN": "pat-naX-xxxx..." }
    }
  }
}

Reload the window, then ask Claude: "Use my hubspot tools — what deals do I have and what stage is each in?"

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "hubspot": {
      "command": "hubspot-mcp",
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-naX-xxxx..."
      }
    }
  }
}

Restart Claude Desktop, and the HubSpot tools appear. Try: "Search my HubSpot for deals in the proposal stage and show their amounts."

Development

git clone https://github.com/MBAD753/hubspot-mcp
cd hubspot-mcp
python -m venv .venv
.venv\Scripts\Activate.ps1      # Windows (PowerShell)
# source .venv/bin/activate     # macOS / Linux
pip install -e ".[dev]"
pytest          # run tests (mocked HTTP — no real API calls)
ruff check .    # lint

Roadmap

• v1 (now): read-only search + fetch across contacts, deals, companies, quotes.

• v2: opt-in write operations (create contact, update deal stage, add note, create quote), gated behind an explicit environment flag and separate write scopes.

License

MIT © Marcus Bickel