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)

Tools

Tool	What it does
search_contacts(query, limit)	Search contacts by name/email/company
get_contact(contact_id)	Full detail for one contact
search_deals(query, stage, limit)	Search/filter deals by name and stage
get_deal(deal_id)	Full deal detail + associated contacts/company
search_companies(query, limit)	Search companies by name/domain
get_company(company_id)	Full company detail
list_quotes(deal_id, limit)	List quotes, optionally for one deal
get_quote(quote_id)	Full quote detail + line items
get_pipeline_stages()	List deal pipelines and their stages

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