# HubSpot MCP Server

An [MCP](https://modelcontextprotocol.io) server that exposes HubSpot CRM
operations as tools over stdio, so any MCP client can query and modify your
HubSpot data.

## Tools

| Tool             | Purpose                                    |
| ---------------- | ------------------------------------------ |
| `getContact`     | Retrieve a Contact by id                   |
| `searchContacts` | Search Contacts by name / email            |
| `listDeals`      | List Deals, optionally filtered by stage   |
| `createContact`  | Create a new Contact                       |
| `updateDeal`     | Update an existing Deal                    |
| `getCompany`     | Retrieve a Company by id                   |

## Setup

1. Install and build:

   ```bash
   npm install
   npm run build
   ```

2. In HubSpot, create a **Private App**
   (Settings -> Integrations -> Private Apps) and grant the CRM scopes you
   need (contacts read/write, deals read/write, companies read). Copy its
   access token.

3. Configure credentials:

   ```bash
   cp .env.example .env
   # then edit .env and paste your token into HUBSPOT_ACCESS_TOKEN
   ```

4. Run:

   ```bash
   npm start        # runs dist/index.js
   # or during development:
   npm run dev
   ```

   You should see `HubSpot MCP server running on stdio.`

## Using with VS Code Copilot (incl. Codespaces)

Create `.vscode/mcp.json` in your workspace root:

```json
{
  "servers": {
    "hubspot": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "${input:hubspot_token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "hubspot_token",
      "description": "HubSpot Private App access token",
      "password": true
    }
  ]
}
```

Open the file, click **Start** above the server entry, switch Copilot Chat to
**Agent mode**, and the HubSpot tools appear.

## Using with Claude Desktop

```json
{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["/absolute/path/to/hubspot-mcp/dist/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your_private_app_access_token"
      }
    }
  }
}
```

## Notes

- Auth is a single static bearer token (the Private App access token) — no
  OAuth exchange needed.
- `listDeals` uses HubSpot's search endpoint when a stage filter is supplied,
  and a plain paginated list otherwise.
- Deal stages and pipelines are referenced by their internal ids, which differ
  per portal — check Settings -> Objects -> Deals -> Pipelines.