HubSpot Connector

SKILL.md

---
name: hubspot-connector
description: "Access HubSpot CRM with managed OAuth. Create, read, update, and search contacts, companies, deals, and tickets. Use when the user wants to manage CRM records, search HubSpot contacts, create deals, update ticket status, or query HubSpot data."
metadata:
  polly:
    polly_managed_connector: true
    auth:
      - env: HUBSPOT_ACCESS_TOKEN
        type: oauth2
        integration_id: hubspot-mcp
        description: HubSpot OAuth access
        scopes:
          - crm.objects.contacts.read
          - crm.objects.contacts.write
          - crm.objects.companies.read
          - crm.objects.companies.write
          - crm.objects.deals.read
          - crm.objects.deals.write
          - crm.objects.tickets.read
          - crm.objects.tickets.write
    primaryEnv: HUBSPOT_ACCESS_TOKEN
---

# HubSpot Connector

Access HubSpot CRM through the HubSpot API v3 using managed OAuth.

## First-Time Setup

If HubSpot is not connected yet, run:

`manage_auth(action="connect", integration_id="hubspot-mcp", auth_env="HUBSPOT_ACCESS_TOKEN")`

## Auth & Security

- Authentication is managed by Polly + Nango from `metadata.polly.auth`
- Never ask users to paste tokens in chat
- Never print or log token values
- If auth fails, reconnect with:
  `manage_auth(action="connect", integration_id="hubspot-mcp", auth_env="HUBSPOT_ACCESS_TOKEN")`

## Base URL

`https://api.hubapi.com`

All requests include:

`Authorization: Bearer $HUBSPOT_ACCESS_TOKEN`

## Quick Usage

List contacts:

```bash
curl -sS \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/crm/v3/objects/contacts?limit=10"
```

Get a contact:

```bash
curl -sS \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/crm/v3/objects/contacts/<contactId>"
```

Create a contact:

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"email":"user@example.com","firstname":"Jane","lastname":"Doe"}}' \
  "https://api.hubapi.com/crm/v3/objects/contacts"
```

Update a contact:

```bash
curl -sS -X PATCH \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"phone":"555-0100"}}' \
  "https://api.hubapi.com/crm/v3/objects/contacts/<contactId>"
```

Search contacts:

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filterGroups":[{"filters":[{"propertyName":"email","operator":"CONTAINS_TOKEN","value":"example.com"}]}],"limit":10}' \
  "https://api.hubapi.com/crm/v3/objects/contacts/search"
```

List companies:

```bash
curl -sS \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/crm/v3/objects/companies?limit=10"
```

Create a deal:

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"dealname":"New Deal","dealstage":"appointmentscheduled","amount":"5000"}}' \
  "https://api.hubapi.com/crm/v3/objects/deals"
```

List tickets:

```bash
curl -sS \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/crm/v3/objects/tickets?limit=10"
```

## Rules

- The same CRUD and search patterns apply to companies (`/crm/v3/objects/companies`), deals (`/crm/v3/objects/deals`), and tickets (`/crm/v3/objects/tickets`)
- For pagination, pass `after` cursor from prior responses
- On API errors, surface status + response body clearly
- On 401/403, reconnect with `manage_auth(action="connect", integration_id="hubspot-mcp", auth_env="HUBSPOT_ACCESS_TOKEN")`
- Never log, echo, or expose credential values in any output