Connect HubSpot CRM to Hermes Agent or OpenClaw with Composio

阅读中文版

Start with the next customer meeting

Before a call, ask the agent for the customer's contact details, open deals, recent notes, and unresolved follow-ups. After the call, have it propose the exact CRM changes. This keeps research and record updates in one conversation, while giving you a chance to catch the wrong contact, currency, or sales stage.

This guide uses the HubSpot toolkit, which appeared on the first page of Composio's Popularity-sorted catalog when checked on October 5, 2026. It is a CRM tool integration for both frameworks.

Connect the hosted account

Hermes Agent and OpenClaw on Launch use the same connection page. You need access to the intended HubSpot account and permission to install the integration there.

1. Open Dashboard → Integrations, search HubSpot, and choose the exact app card. The toolkit slug is hubspot.
2. Click Connect and complete the displayed authorization flow. The hosted curated connector uses managed OAuth; select the correct HubSpot account if you belong to several.
3. Review the requested access and finish authorization. Wait for the card to show Connected.
4. Ask the agent to confirm its active HubSpot connection and read a small set of contacts. No record changes are needed for this check.

For your own Composio project, the toolkit reference also documents API Key authentication using a HubSpot private app token. Keep that token in the connection form, not in chat or the MCP project-key header. Configure contact and deal read scopes for a briefing; add the matching write scopes only when your workflow needs updates. HubSpot's account permissions and feature availability still apply.

Discover the actions before filling in parameters

composio connections
composio search hubspot list contacts
composio search hubspot list deals
composio search hubspot update contact

The hosted skill returns action schemas. Inspect them before executing: IDs, requested properties, filters, and pagination belong to the selected action. Useful actions include:

• HUBSPOT_LIST_CONTACTS: read contacts and their requested properties.
• HUBSPOT_LIST_DEALS: review deal records.
• HUBSPOT_LIST_CONTACT_NOTES: inspect notes linked to a contact.
• HUBSPOT_GET_PIPELINE_BY_ID: check a pipeline before choosing a stage.
• HUBSPOT_CREATE_CONTACT and HUBSPOT_CREATE_DEAL: create approved records.
• HUBSPOT_UPDATE_CONTACT: update selected properties on a known record.

For example, this hosted command reads five contacts with a small property set:

composio execute HUBSPOT_LIST_CONTACTS '{"limit":5,"properties":["firstname","lastname","email"]}'

For contact reads, check crm.objects.contacts.read; deal reads use crm.objects.deals.read. Updates need the corresponding .write scopes. Property and pipeline tools may need additional scopes. Discover the schema each time: contact creation uses top-level fields, while HUBSPOT_UPDATE_CONTACT uses contactId and a properties object.

Use my connected HubSpot account. Read up to five contacts and return their IDs, names, and email addresses. Show the connected account context if available. Do not create, update, merge, archive, send, or enroll anything.

A meeting-to-CRM workflow that avoids duplicate records

1. Find the existing contact by an exact email match and retain its record ID. If there are multiple matches, show them before proceeding.
2. Read its linked deal context and the relevant pipeline. Use the internal stage and property values returned by HubSpot rather than guessing from display labels.
3. Prepare a preview from the meeting notes: record ID, property name, old value, proposed value, and any new record or association.
4. Apply only the approved changes. Read the changed record again and report its ID and resulting values.

Find the contact matching this email and show the open deal context. Based on these meeting notes, propose the next changes with record IDs and before/after values. Wait for my approval before applying them. Do not send email or enroll the contact in a workflow.

A later routine can brief you on deals by stage, identify records missing an owner, or prepare follow-up drafts using connected Gmail. Keep the CRM update and the email send as separate steps. Airtable can hold a reviewed reporting table, but decide which app owns each field before syncing both ways.

Pagination, scopes, and provider limits

Request only the properties you need and follow the action's returned pagination cursor. A single page is not a complete CRM export. For indexed searches, HubSpot documents separate limits and a delay before newly changed records appear in results; read a returned record ID directly when verifying a write. See the CRM search guide.

On throttling, pause according to the provider response and retry with backoff. After an ambiguous create timeout, check for the intended record before repeating the create. Your HubSpot plan, API limits, Composio limits, and agent model usage are separate constraints; connecting the app does not remove any of them.

Troubleshooting HubSpot

• The wrong contacts appear: confirm the HubSpot account chosen during OAuth, especially when your login has access to multiple accounts.
• 401 or an expired connection: reconnect through the integration page. For a private app token, check whether it was rotated or revoked.
• 403 or missing scopes: check the object's read or write scopes and the account's available features. Contacts working does not prove deals or marketing email are authorized.
• A property or stage is rejected: read its internal name and valid options from HubSpot. A custom label is not necessarily its API value.
• A trigger requires developer credentials: this guide covers tool calls. Composio documents a separate app-ID and developer-key setup for HubSpot triggers; an OAuth connection alone does not configure event delivery.

Self-hosted: configure Hermes and OpenClaw separately

For an agent you run yourself, connect the app in your own Composio project. Create a single-toolkit MCP configuration with its auth configuration and the tools your workflow needs. Generate the complete MCP URL for the same user ID that owns the ACTIVE connection. A hosted Launch connection does not automatically carry over to your own project.

Composio: single-toolkit MCP setup

Replace the URL placeholder with the generated address. The x-api-key header uses your own Composio project key, not an Airtable or HubSpot token. Set COMPOSIO_API_KEY in the agent process environment and keep the key and MCP URL private. Merge the server entry into your existing file, preserving other settings.

Hermes Agent

Set the environment variable in ~/.hermes/.env and add the server under mcp_servers in ~/.hermes/config.yaml:

mcp_servers:
  composio:
    url: "YOUR_GENERATED_PLATFORM_MCP_URL"
    headers:
      x-api-key: "${COMPOSIO_API_KEY}"

Run hermes mcp test composio to check the connection, then start a new session or use /reload-mcp in the CLI.

Hermes upstream MCP configuration

OpenClaw

Use an OpenClaw release with the native mcp commands. Add the server under mcp.servers in ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "composio": {
        "url": "YOUR_GENERATED_PLATFORM_MCP_URL",
        "transport": "streamable-http",
        "headers": {
          "x-api-key": "${COMPOSIO_API_KEY}"
        }
      }
    }
  }
}

Ensure the Gateway process receives COMPOSIO_API_KEY; restart that service after changing its environment. Run openclaw mcp doctor composio --probe and begin a new session. Upgrade first if your version lacks these commands, rather than adding unsupported fields to a strictly validated configuration.

OpenClaw upstream MCP commands · HTTP transport configuration

Successful MCP discovery proves that the tool server is reachable. Finish with this guide’s read-only request to verify the app account and data access. The composio shell commands above are supplied by Launch’s hosted skill; a standalone MCP setup uses each framework’s MCP client.

Does HubSpot through Composio work on Hermes Agent?

Yes. Hosted Hermes Agent and OpenClaw share the Launch Integrations page and Composio skill. Self-hosted installations use different MCP configuration files, shown above.

Do I need a HubSpot private app token?

The managed OAuth flow does not require one. In your own Composio project, the API Key method uses a HubSpot private app access token, not your account password or an old HubSpot API key.

Does a Connected badge mean every CRM action is available?

No. It confirms the connection, while actual calls also depend on granted scopes, account features, and the selected toolkit tools. Test contact and deal reads separately.

Will this automatically email my leads?

Connecting the CRM does not create a follow-up campaign. Start with a briefing and draft. Sending marketing email or enrolling contacts in workflows is a separate action that can affect real customers.