home / skills / asu-le / claude-plugins / hubspot

hubspot skill

safe

This skill helps you access HubSpot CRM data to view contacts, companies, and deals using the hubspot-api-client for informed decisions.

npx playbooks add skill asu-le/claude-plugins --skill hubspot

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.6 KB

---
name: hubspot
description: Access HubSpot CRM to view contacts, companies, deals, tickets, and marketing data. Use when user mentions HubSpot, CRM, contacts, companies, deals, leads, or marketing automation. Uses Python hubspot-api-client for reliable access.
---

# HubSpot CRM Client

## First: Check Prerequisites

### Step 1: Check Python
```bash
python3 --version 2>/dev/null || echo "NOT_INSTALLED"
```

**If NOT installed**:
- macOS: `brew install python3`
- Windows: Download from https://python.org

### Step 2: Check hubspot-api-client
```bash
python3 -c "import hubspot; print('OK')" 2>/dev/null || echo "NOT_INSTALLED"
```

**If NOT installed**:
```bash
pip3 install hubspot-api-client
```

### Step 3: Check HubSpot Access Token
```bash
echo "HUBSPOT_ACCESS_TOKEN=${HUBSPOT_ACCESS_TOKEN:+SET}"
```

**If NOT set**, guide the user:

> **To get your HubSpot Access Token:**
> 1. Go to HubSpot → Settings (gear icon)
> 2. Navigate to **Integrations** → **Private Apps**
> 3. Click **Create a private app**
> 4. Name it "Claude Assistant"
> 5. Go to **Scopes** tab and select:
>    - `crm.objects.contacts.read`
>    - `crm.objects.companies.read`
>    - `crm.objects.deals.read`
>    - `crm.objects.owners.read`
>    - (add write scopes only if needed)
> 6. Click **Create app** → **Continue Creating** → **Show token**
> 7. Copy the access token
>
> **Then set it:**
> ```bash
> echo 'export HUBSPOT_ACCESS_TOKEN="pat-na1-xxxxxxxx"' >> ~/.zshrc
> source ~/.zshrc
> ```
>
> **Restart Claude Code after setting the token.**

---

## Quick Examples

**List contacts:**
```bash
python3 -c "
import os
from hubspot import HubSpot

client = HubSpot(access_token=os.environ['HUBSPOT_ACCESS_TOKEN'])
contacts = client.crm.contacts.basic_api.get_page(limit=10)
for c in contacts.results:
    print(f'{c.properties.get(\"firstname\", \"\")} {c.properties.get(\"lastname\", \"\")} - {c.properties.get(\"email\", \"\")}')
"
```

**List companies:**
```bash
python3 -c "
import os
from hubspot import HubSpot

client = HubSpot(access_token=os.environ['HUBSPOT_ACCESS_TOKEN'])
companies = client.crm.companies.basic_api.get_page(limit=10)
for c in companies.results:
    print(f'{c.properties.get(\"name\", \"Unknown\")} - {c.properties.get(\"domain\", \"\")}')
"
```

**List deals:**
```bash
python3 -c "
import os
from hubspot import HubSpot

client = HubSpot(access_token=os.environ['HUBSPOT_ACCESS_TOKEN'])
deals = client.crm.deals.basic_api.get_page(limit=10, properties=['dealname', 'amount', 'dealstage'])
for d in deals.results:
    print(f'{d.properties.get(\"dealname\", \"\")} - \${d.properties.get(\"amount\", \"0\")}')
"
```

See `api-reference.md` for complete patterns.

Overview

This skill connects to HubSpot CRM to view contacts, companies, deals, tickets, owners, and marketing data. It uses the official Python hubspot-api-client and an access token to retrieve and display CRM records. The skill is intended for read-focused queries about leads, accounts, pipelines, and campaign activity. It provides quick programmatic examples to list and inspect key objects.

How this skill works

The skill authenticates using a HubSpot private app access token and calls the hubspot-api-client endpoints for contacts, companies, deals, tickets, and owners. It retrieves pages of records and selected properties, then formats concise summaries for responses. The skill can be extended to include write scopes but defaults to read-only access unless additional permissions are granted.

When to use it

You mention HubSpot, CRM, contacts, companies, deals, tickets, or owners.
You need a quick list or summary of recent leads, accounts, or deal pipelines.
You want contact or company property values (email, domain, owner).
You want to verify HubSpot data is present or inspect sample records.
You need to confirm API access or troubleshoot missing permissions.

Best practices

Use a HubSpot private app access token stored in an environment variable (HUBSPOT_ACCESS_TOKEN).
Limit page sizes and request only required properties to reduce latency and API usage.
Grant only the scopes needed; add write scopes only when you intend to modify data.
Cache results for frequent queries and respect HubSpot rate limits.
Use clear property names when requesting properties (e.g., dealname, amount, dealstage).

Example use cases

List the 10 most recent contacts and show name and email.
Fetch 10 companies and display company name and primary domain.
Retrieve open deals with deal name, amount, and deal stage for pipeline review.
Confirm which owner is assigned to a contact or company.
Validate that the HUBSPOT_ACCESS_TOKEN is set and that the client can fetch a basic page of contacts.

FAQ

How do I get the HubSpot access token?

Create a private app in HubSpot Settings → Integrations → Private Apps, grant the necessary read scopes, create the app, and copy the generated token. Store it in an environment variable named HUBSPOT_ACCESS_TOKEN.

What Python package does this skill use?

It uses the official hubspot-api-client Python package. Install it with pip3 install hubspot-api-client and verify import with a short Python check.