# hubspot-mcp

[![CI](https://github.com/MBAD753/hubspot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MBAD753/hubspot-mcp/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

`hubspot-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) 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:

```bash
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:

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

> **Tip:** Use a free [HubSpot developer/test account](https://developers.hubspot.com) 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):

```bash
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`:

```json
{
  "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`:

```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

```bash
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