# How to connect HubSpot to Hermes Agent (no API keys)

> Connect HubSpot to Hermes with ClawLink in one click — 224 tools your AI agent can call from chat via hosted OAuth. No API keys, no manual setup.

Web version: https://claw-link.dev/hermes/hubspot

Most guides for giving Hermes Agent HubSpot access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical HubSpot setup: pair once in the browser and your always-on Hermes agent can act on HubSpot for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to HubSpot.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect HubSpot** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect hubspot  # connect HubSpot (browser OAuth)
npx -y @useclawlink/cli actions hubspot  # list available actions
npx -y @useclawlink/cli run hubspot <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect HubSpot in the [ClawLink dashboard](https://claw-link.dev/dashboard) — a one-click OAuth approval, no API keys.

Verify the connection by asking Hermes:

> Use hubspot_create_contact to create a contact for Jane Doe at jane@example.com, company Acme Inc, and confirm the new contact id and that the email is unique.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once HubSpot is connected in the dashboard, that agent calls the same 224 HubSpot tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## HubSpot MCP for Hermes

Looking for a HubSpot MCP server for Hermes Agent? ClawLink connects HubSpot to Hermes Agent and exposes 224 HubSpot tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw HubSpot integration](https://claw-link.dev/openclaw/hubspot) works the same way.

The AI Overview for the exact query this page ranks #4 on teaches a Composio Connect walkthrough: install their CLI, ask Hermes to authenticate, and add a Connect MCP block to ~/.hermes/config.yaml. ClawLink's answer is shorter: install the plugin, connect HubSpot in the browser, and 224 tools work from chat with nothing added to your Hermes config. HubSpot has deprecated legacy API keys, so the manual path the ecosystem now teaches is a private app with scopes, a token you create and rotate yourself; none of that exists in this flow, because the connection is hosted OAuth: no private app, no OAuth app, no token to manage. For context on what the agent can reach, HubSpot's own Breeze agents live inside HubSpot, while this connection gives an external runtime a CRM surface with the scopes the connected user's portal allows.

## What the Hermes Agent HubSpot integration can do

224 HubSpot tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 224.

### 30 of 224 HubSpot tools for Hermes

| Tool | What it does |
|---|---|
| **Create company** `hubspot_create_company` | Create a HubSpot company |
| **Create contact** `hubspot_create_contact` | Create a HubSpot contact |
| **Create deal** `hubspot_create_deal` | Create a HubSpot deal |
| **Create task** `hubspot_create_task` | Create a HubSpot task |
| **Get company** `hubspot_get_company` | Get a HubSpot company by ID |
| **Get deal** `hubspot_get_deal` | Get a HubSpot deal by ID |
| **Get ticket** `hubspot_get_ticket` | Get a HubSpot ticket by ID |
| **Read contact** `hubspot_read_contact` | Get a HubSpot contact by ID |
| **Retrieve owners** `hubspot_retrieve_owners` | List HubSpot owners and users |
| **Search companies** `hubspot_search_companies` | Search HubSpot companies |
| **Search contacts by criteria** `hubspot_search_contacts_by_criteria` | Search HubSpot contacts |
| **Search CRM objects by criteria** `hubspot_search_crm_objects_by_criteria` | Search HubSpot CRM objects |
| **Search deals** `hubspot_search_deals` | Search HubSpot deals |
| **Search tickets** `hubspot_search_tickets` | Search HubSpot tickets |
| **Update contact** `hubspot_update_contact` | Update a HubSpot contact |
| **Audit pipeline changes** `hubspot_audit_pipeline_changes` | Retrieves a reverse chronological audit log of all changes for a specific, existing HubSpot CRM |
| **Batch read companies by properties** `hubspot_batch_read_companies_by_properties` | Batch-retrieves up to 100 HubSpot company records by their IDs in a single request |
| **Fetch import error details** `hubspot_fetch_import_error_details` | Fetches a paginated list of read-only error details for a specific HubSpot CRM import |
| **Fetch recording settings** `hubspot_fetch_recording_settings` | Fetches call recording settings for a specified, existing HubSpot calling extension app |
| **Get AB email variation** `hubspot_get_ab_email_variation` | Retrieves the alternate variation of a specified A/B marketing email; the `emailId` must |
| **Get account info** `hubspot_get_account_info` | Gets current HubSpot account info (email, hubId, user details) using access-token lookup |
| **Get active imports list** `hubspot_get_active_imports_list` | Retrieves a list of currently active import jobs in HubSpot for monitoring ongoing data |
| **Get aggregated statistic intervals** `hubspot_get_aggregated_statistic_intervals` | Retrieves aggregated statistics for marketing emails (e.g., send counts), grouped by specified |
| **Get aggregated statistics** `hubspot_get_aggregated_statistics` | Retrieves aggregated statistics for marketing emails, optionally within an ISO8601 formatted |
| **Get all marketing emails for a hub spot account** `hubspot_get_all_marketing_emails_for_a_hub_spot_account` | Fetches a list of marketing emails from a HubSpot account, with options for filtering, sorting |
| **Get contact IDS** `hubspot_get_contact_ids` | Fetches a list of contact IDs for a specific HubSpot campaign based on interaction type |
| **Get deals** `hubspot_get_deals` | Retrieves multiple HubSpot deals by their IDs in a single batch request |
| **Get emails** `hubspot_get_emails` | Retrieves multiple HubSpot email engagement records by their IDs in a single batch request |
| **Get import record information** `hubspot_get_import_record_information` | Retrieves a comprehensive summary of a specific HubSpot CRM import record by its `importId` |
| **Get marketing email draft** `hubspot_get_marketing_email_draft` | Retrieves the draft version of a marketing email by its `emailId`; if no draft exists, returns |

## Example prompts

**Create a contact**

> Use hubspot_create_contact to create a contact for Jane Doe at jane@example.com, company Acme Inc, and confirm the new contact id and that the email is unique.

**Search contacts**

> Use hubspot_search_contacts_by_criteria to find contacts with email domain example.com, sort by most recently created, and list name, company, and creation date.

**Read a deal and its company**

> Use hubspot_get_deal for the deal id I give you and hubspot_get_company for the company id, then summarize the deal stage, amount, and owner in one paragraph.

**Audit pipeline changes**

> Use hubspot_audit_pipeline_changes for pipeline 123 and tell me who moved which deal and when over the last 30 days, in reverse chronological order.

## What the 224 HubSpot tools cover

The CRM surface, checked against the live manifest on 2026-08-02.

- **Search is generic across object types.** `hubspot_search_crm_objects_by_criteria` searches any CRM object type, contacts, companies, deals, tickets, with filters, sorting, and pagination, and its manifest notes that property names use their internal names in filters.
- **Batch reads exist.** `hubspot_batch_read_companies_by_properties` retrieves up to 100 company records in one request with custom property selection, and `hubspot_get_deals` and `hubspot_get_emails` batch-read their record types by id.
- **Record creation.** `hubspot_create_contact`, `hubspot_create_company`, `hubspot_create_deal`, and `hubspot_create_task` are the write entry points, and all four are confirm-before-execute tools in this integration.
- **Account context.** `hubspot_get_account_info` returns the connected account's email, hub id, and user details via access-token lookup; it is the tool to call when the agent needs to confirm which portal it is acting on.
- **Audit trail.** `hubspot_audit_pipeline_changes` returns a reverse-chronological log of every change to a specific pipeline, which is the closest thing to an activity history in the CRM surface.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want HubSpot working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Connection flow** | Register a HubSpot app, configure redirect URLs, manage consent details, and reconnect users when auth settings drift. | Users connect HubSpot through the hosted browser flow and ClawLink keeps the token lifecycle out of your app code. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for HubSpot. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right HubSpot actions to the runtime in a format your agent can reliably use. | 224 tools for HubSpot are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes HubSpot to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect HubSpot in the browser, and the 224 tools above work from chat. There is no SDK, no config file, and no API key handling. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use HubSpot
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

### Connection succeeds but no tools appear
Reconnect HubSpot from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling HubSpot tools
HubSpot tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every HubSpot call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### HubSpot returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### HubSpot API returns 403 "insufficient permissions" on a connected account
HubSpot's own community threads answer this with scope checking, and their failure modes are different from the generic causes: the connected user may lack a scope the tool needs, such as crm.objects.contacts.write, or the object type may be tier-gated so the portal's plan does not include it, or the request hits field-level permissions on the user's role. Some tools also require the user to be a Super Admin, for example for marketplace app access. Walk the checklist in that order, and keep the placeholder trap in mind: an id like YOUR_ID from documentation 403s on the write even when the scope is fine, so have the agent search or list first and retry with a real id. If the scope itself is the problem, the fix is a HubSpot-side permission or plan change, not a reconnect.

### HubSpot returns a permission error even though the account is connected
The fan-out queries for this page keep rewriting the question this way, so the checklist: start a fresh chat so the runtime reloads the tool catalog, because a stale catalog can surface as a tool-level failure. Then check the id the agent sent, because placeholder ids from documentation are the most common cause of a 403 on an otherwise healthy connection. Then check portal permissions for the scopes the failing tool needs, including whether the object type is included in the portal's plan. Reconnect last, and only after confirming the token side, because HubSpot can also force re-authorization when the app's scopes change.

### "hubspot mcp tool not found" errors from the HubSpot CLI don't apply here
The query space answers this with local developer setup: `npm install -g @hubspot/cli`, run `hsmcp setup`, and edit IDE config files. A hosted connection has no local MCP server, so none of those errors or fixes exist here: there is no CLI to install and no config file for a missing tool to come from. If a HubSpot tool is missing from your agent's catalog, reconnect HubSpot from the dashboard and start a fresh chat so the runtime reloads the tool list.

### OAuth finished in the browser but the account is still missing
Try reconnecting HubSpot and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

### Is there a Hermes Agent HubSpot integration?
Yes. ClawLink is the fastest way to connect Hermes to HubSpot: link your HubSpot account once in the browser and Hermes Agent can call the HubSpot API through 224 ready-made tools — no custom code or token handling.

### How do I connect HubSpot to Hermes with ClawLink?
Install the plugin with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then pair once: run `hermes clawlink begin`, approve the link in your browser, and run `hermes clawlink finish`. Connect HubSpot in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

### How long does it take to connect HubSpot to Hermes Agent?
About two minutes. Sign in, click Connect next to HubSpot in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

### Why use ClawLink instead of wiring HubSpot up myself?
The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want HubSpot working from chat.

### Do I need a HubSpot private app token?
No. HubSpot has deprecated legacy API keys, so the manual path is now a private app: Settings, then Integrations, then Private Apps, create an app, pick scopes, and copy the token it shows. ClawLink replaces all of that with hosted OAuth. You connect HubSpot in the browser, the scopes come from the OAuth consent rather than a hand-built scope list, and there is no token for you to create, rotate, or store anywhere.

### Why use ClawLink instead of the Composio Connect CLI?
Composio's own walkthrough is developer setup: pipe their install script into a shell, have Hermes authenticate, and add a Connect MCP block to ~/.hermes/config.yaml. ClawLink is the hosted version of that idea with the config file removed: you install the plugin once, connect HubSpot in the dashboard, and the 224 tools are callable from the next message. If you already run Composio and want its MCP config, that path works; if you want the same capability without a config file, this is the page.

### Is it safe to connect HubSpot to an AI agent?
HubSpot's own security pages and the governance writeups answer yes with caveats, and the caveats matter here. The connection uses OAuth consent, so the agent can only act with the permissions of the portal and user you authenticate with, and you can revoke it from the ClawLink dashboard at any time. HubSpot's published position is that its platform does not train on customer data; what the agent does with your CRM records is governed by the scopes and by your own instructions, so constrain what it may read and write just as you would any staff member with portal access.

### Why not use HubSpot's own Breeze agents?
HubSpot's built-in Breeze agents answer the no-API-key story inside HubSpot: they are native to the portal, plan-gated, and designed around HubSpot workflows. They do not give an external runtime like Hermes Agent an API surface, which is the gap this connection fills. If your agent needs to mix CRM data with your other connected tools in one conversation, it needs a HubSpot connection it can call directly.

### How many HubSpot tools does this integration expose?
224 tools, counted from the generated manifest on 2026-08-02. Some index snippets still show an older copy that says 15; the page and its tool list are current at 224, and the agent can call all of them. The 30 featured on the page are the most-used CRM operations.

### Hermes paired but still can't use HubSpot
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

## Related

- [CentralStationCRM tools](https://claw-link.dev/hermes/centralstationcrm) — CentralStationCRM is an easy-to-use CRM software focusing on collaboration and long-term customer relationships.
- [Hermes Salesforce integration](https://claw-link.dev/hermes/salesforce) — Manage CRM data and workflows
- [Hermes RepairShopr integration](https://claw-link.dev/hermes/repairshopr) — RepairShopr is a comprehensive repair shop management software designed to streamline operations, manage customer relationships, and enhance business efficiency.