By Ira Bodnar, Ryze AI · Updated
Quick answer
To connect Claude Code to HubSpot, connect HubSpot in a Ryze AI workspace with HubSpot's own sign-in, run claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp, then run /mcp inside Claude Code, select ryze and sign in. Start a new session and ask about your HubSpot contacts or deals.
- In Ryze AI open Integrations, click Connect on HubSpot, choose the portal and approve the permissions
- In your terminal run the claude mcp add command
- Inside Claude Code run /mcp, select ryze and sign in
- Allow the workspace on the Ryze AI page and ask your first question
Before you start
- Claude Code access. Anthropic's setup page says you need a Pro, Max, Ultra, Team, Enterprise or Console account. The free claude.ai plan leaves Claude Code out. Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry also work as providers. Remote MCP servers have no separate plan requirement on Anthropic's MCP page.
- Super Admin or App Marketplace Access in HubSpot. Only users holding one of these permissions can install an app in HubSpot. Everyone else asks a Super Admin to run the connection. HubSpot shows an install error when the portal's plan does not include a scope the app asks for.
- A Ryze AI plan or trial. Paid Ads costs $89 per month and starts with 7 free days. SEO Starter costs $129 per month with 3 free days and covers Content Plan articles published to a HubSpot blog. Agency costs $279 per month. Adding the connector costs nothing, while the HubSpot tools run only under an active plan or trial.
How to connect Claude Code to HubSpot
Three steps happen in HubSpot and Ryze AI, three in Claude Code. The connector URL is the same for every user.
Connect HubSpot in Ryze AI
Create a Ryze AI account or sign in, open Integrations, find the HubSpot card and click Connect. Ryze AI sends you to HubSpot to authorize.
Choose the portal and approve the permissions
Sign in to HubSpot, choose the account (portal) and click Choose Account, then approve the permissions HubSpot lists. HubSpot returns you to Ryze AI with the connection saved. For blog publishing only, click View on the HubSpot card, pick the Blog and the Author and click Save.
Register the connector in Claude Code
Open a terminal and run claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp. The name ryze is yours to choose, and it becomes part of the tool names Claude Code shows. Add --scope user if you want the server in every project.
Sign in from Claude Code
Start Claude Code, type /mcp, pick ryze and choose to authenticate. A shell alternative is claude mcp login ryze, and its --no-browser flag prints the link for machines without a browser, such as an SSH session.
Allow the workspace
The browser opens a Ryze AI page. Sign in if it asks, tick the workspace where you connected HubSpot and click Allow connection. Back in the terminal, claude mcp get ryze reports the state of the server.
Start a new session and ask your first question
Claude Code defers MCP tools and loads them when a task needs them. Try: Search HubSpot deals created in the last 30 days and list the deal name, amount and stage.
The Ryze AI HubSpot guide covers the HubSpot side of the connection, and the Claude Code MCP docs cover the client commands.
OAuth, API key and claude.ai connectors
Claude Code accepts the Ryze AI connector three ways. Pick the one that matches where the session runs.
Terminal sign-in with OAuth
claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp --scope userUse this on your own laptop. Without a scope flag the server is saved as local, visible only in the project folder you ran it from. With --scope user every project sees it. With --scope project the command writes .mcp.json, which teammates get through version control; each of them approves that server once in an interactive session.
Terminal with a Ryze AI API key
claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp --header "Authorization: Bearer rk_live_..."Create the key in Ryze AI under Workspace Settings, Profile, API keys, Create key. It appears once, so copy it then. Ryze AI's help center notes that keys are accepted at /mcp and not at /sse. A configured Authorization header that the server rejects marks the connection as failed in Claude Code, which never retries with OAuth, so swap the key if that happens. Keep it out of repositories and shared shell history.
Connectors from your claude.ai account
Add Ryze AI on claude.ai under Customize, Connectors and complete the sign-in, then sign in to Claude Code with that same subscription account and run /mcp. The entry carries a marker showing it came from claude.ai. Team and Enterprise plans let only admins add servers there. The sync needs a claude.ai subscription login; it does not load when Claude Code runs on ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper or a third-party provider.
Scripts and limits
Non-interactive runs (claude -p and Agent SDK) have no way to complete OAuth, so authenticate beforehand with /mcp or claude mcp login ryze, or pass a Ryze AI API key. Output size matters for CRM lists: Claude Code prints a warning once a tool returns more than 10,000 tokens and truncates MCP output at 25,000 tokens unless you set MAX_MCP_OUTPUT_TOKENS higher. A tool call over HTTP times out after five idle minutes without a response or progress.
Claude web, ChatGPT and Cursor
The same URL works in other MCP clients. HubSpot is connected once in Ryze AI, so nothing changes on the HubSpot side.
Claude on the web and Desktop
Open Customize, Connectors, click + Add, choose Add custom connector, name it Ryze AI and enter https://connector.get-ryze.ai/mcp.
ChatGPT
OpenAI says full custom MCP server support is for ChatGPT Business and Enterprise/Edu on the web, and Pro can connect custom MCP servers with read and fetch permissions only. Add the URL as a custom MCP server and choose OAuth.
Cursor
Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Cursor runs OAuth with PKCE and asks for approval before using MCP tools by default.
{ "mcpServers": { "ryze": { "url": "https://connector.get-ryze.ai/mcp" } } }HubSpot permissions and scopes
The HubSpot side of the connection is a standard HubSpot OAuth app install. Three things decide what Claude Code can reach.
- Who can connect
- A HubSpot Super Admin or a user with App Marketplace Access. If the portal's plan lacks a scope the app requires, HubSpot shows an error during install.
- Which portal
- One connection is one HubSpot portal. If your login sees several, HubSpot asks you to choose one. Ryze AI documents adding more portals to one workspace under View, Add one more account; the starred portal is the primary and is used unless you name another.
- What the token covers
- HubSpot notes that an access token carries the scopes the app requested, and the installing user's own record limits do not apply. Someone who can only view their own contacts but grants a contacts read scope gives the app a token that can read all contacts. Connect with a login whose reach you are comfortable sharing.
Scopes behind each action
Ryze AI's help center lists what the agent can do once HubSpot is connected. The table maps each action to the HubSpot scope name from HubSpot's scope reference, so you can match it against the consent screen. The consent screen is the source of truth for the exact list. The tool descriptions mention custom objects, but the requested scopes do not include custom-object scopes, so do not count on them.
| Action in Ryze AI | HubSpot scope |
|---|---|
| Read and edit contacts | crm.objects.contacts.read, crm.objects.contacts.write |
| Read and edit companies | crm.objects.companies.read, crm.objects.companies.write |
| Read and edit deals | crm.objects.deals.read, crm.objects.deals.write |
| Read contact lists | crm.lists.read |
| Look up record owners | crm.objects.owners.read |
| Read and edit CMS blog content | content (HubSpot lists it for CMS Hub Professional or Enterprise, or Marketing Hub Professional or Enterprise) |
Sources: Ryze AI HubSpot guide and HubSpot's scope reference.
Removing access
To remove access, uninstall the app in HubSpot under Settings, Integrations, Connected Apps. In Ryze AI, click View on the HubSpot card and use the trash icon to disconnect a portal. In Claude Code, run claude mcp remove ryze to drop the server.
What Claude Code can do in HubSpot
The Ryze AI connector exposes 5 HubSpot tools: 3 read, 1 write and 1 delete. Each runs as the portal you connected.
| Tool | Type | What it does |
|---|---|---|
| hubspot__listObjects | Read | Lists CRM records of one object type page by page, with the properties you choose and the IDs of associated records. |
| hubspot__search | Read | Searches CRM records through the HubSpot CRM Search API with filter groups, sorts, a text query and chosen properties. |
| hubspot__read | Read | Sends a GET request to any HubSpot JSON API resource, such as a record, property definitions, owners, a list or blog posts. |
| hubspot__write | Write | Creates or updates a HubSpot resource, such as a contact, company, deal or blog post, and adds associations between records. |
| hubspot__delete | Delete | Archives a HubSpot resource by ID, such as a CRM record or blog post. Most CRM deletes go to HubSpot's recycling bin; deleted blog posts may not be recoverable. |
Claude Code can gate each tool with permission rules named mcp__<server>__<tool>, set to allow, ask or deny. Because the server here is called ryze, adding ask rules for mcp__ryze__hubspot__write and mcp__ryze__hubspot__delete means Claude Code stops and prompts before either one runs. On claude.ai, Customize, Connectors, Ryze AI, Tool permissions lets you mark write and delete tools as Needs approval. Inside the Ryze AI chat the Tool approvals setting begins on Skip all approvals, so switch it to Approve write & delete or Manual approve if you want a prompt. Ryze AI scheduled tasks have no approval step.
First 3 prompts to run
HubSpot returns a default subset of properties unless the request names specific fields, so each prompt names the fields it wants. Each answer comes from your own portal, so this page describes what comes back instead of showing sample numbers.
1. Open deals by stage and owner
Search HubSpot deals that are not closed. Return the deal name, amount, stage, close date and owner, and list owners by name using the owners data.
Tools used: hubspot__search on deals, hubspot__read for owners
What comes back: A table of open deals with the fields you named and the owner for each one, built from the records your portal holds.
2. Contacts created recently
List HubSpot contacts created in the last 14 days with first name, last name, email, lifecycle stage and the companies associated with them.
Tools used: hubspot__search or hubspot__listObjects on contacts
What comes back: One row per contact with the properties you asked for and the IDs of the associated companies.
3. Fix a field on one record
Find the HubSpot company named in my last message, show its current industry and lifecycle stage, then propose the update and wait for me to confirm before you change it.
Tools used: hubspot__search, then hubspot__write
What comes back: The company's current values, then a confirmation request. The write runs only after you answer, and only if your approval rules ask first.
Deleting is a separate tool, so ask for it by name and object, and set write and delete tools to ask first as described above. The Ryze AI help center says the agent deletes records or blog posts when explicitly asked.
Ryze AI vs HubSpot's own MCP server
HubSpot runs its own remote MCP server, and its Claude connector is documented for Claude on the web, desktop and mobile. Anthropic's Claude Code docs use the HubSpot URL https://mcp.hubspot.com/anthropic in an example of a user-scope server.
| Option | Setup | HubSpot coverage | Works in |
|---|---|---|---|
| Ryze AI connector | HubSpot sign-in inside Ryze AI, then claude mcp add with one URL and /mcp to sign in | 5 tools: search, list and read records, plus write and delete. CRM contacts, companies and deals, lists, owners and blog content | Claude Code, claude.ai, ChatGPT, Cursor |
| HubSpot remote MCP server | Create an MCP connector in HubSpot under Development, MCP Connectors, then give your client https://mcp.hubspot.com with the client ID and secret. OAuth 2.1 with PKCE is required | 40+ tools across CRM records, activities, content, campaigns, emails, pipelines, properties and more. Access follows your HubSpot user permissions | Any MCP client that supports OAuth with PKCE |
| HubSpot connector for Claude | Claude Settings, Connectors, Browse, HubSpot, Connect. Super Admins and users with App Marketplace Access connect directly | View, create and update CRM records and activities, up to 10 records at a time; no delete | Claude on the web, desktop and mobile, on Pro, Max, Team or Enterprise. HubSpot's article does not mention Claude Code |
HubSpot's own server needs no Ryze AI plan, covers far more HubSpot objects, but you create and manage a connector with client credentials in your portal. Choose it if the work stays inside HubSpot. Choose the Ryze AI connector if you want a short tool list, a HubSpot sign-in handled in Ryze AI and the same URL for your other connected platforms; it needs a Ryze AI plan or trial, and your HubSpot data passes through Ryze AI.
HubSpot's remote MCP page did not state a rate limit in the part checked, so confirm limits in your own HubSpot account before running large jobs.
Sources: HubSpot remote MCP server, HubSpot connector for Claude, Claude Code MCP, Claude Code permissions, Ryze AI HubSpot guide. Checked November 13, 2026.
Errors and fixes
- HubSpot shows an error during the install
- Your HubSpot user is not a Super Admin or lacks App Marketplace Access, or the portal's plan lacks a scope the app requires. Ask a Super Admin to connect HubSpot in Ryze AI, or to grant you the permission.
- Claude Code says the server failed to connect with an API key
- A rejected Authorization header ends in a failed connection, and Claude Code does not try OAuth afterwards. Confirm the key is a live rk_live_ Ryze AI key and the URL ends in /mcp, or delete the server and add it again without --header.
- claude -p or an Agent SDK run cannot sign in
- Headless runs have no browser step. Sign in beforehand in an interactive shell with /mcp or claude mcp login ryze, or switch to the API key method.
- The server does not load from .mcp.json
- A server from .mcp.json stays idle until someone approves it in an interactive session. Accept the prompt when Claude Code shows it.
- No HubSpot tools appear
- Run claude mcp remove ryze, add the server again and open a new session if you registered it before linking HubSpot. Because tools load on demand, the list may also look short until a task calls for them.
- A field is missing from the results
- HubSpot returns a default set of properties unless the request names others. Ask Claude Code for the exact properties you need.
- The wrong HubSpot portal is connected
- Each connection is one portal. Click View on the HubSpot card in Ryze AI, connect the right portal with Add one more account, then remove the wrong one with the trash icon.
- The HubSpot connection stopped working
- The token may have been revoked, for example if someone uninstalled the app under Connected Apps in HubSpot. Click Reconnect on the HubSpot card and authorize again.
- The result is cut off or very large
- Output above 10,000 tokens triggers a warning and anything past 25,000 is cut by default. Request fewer properties or records, or set a higher MAX_MCP_OUTPUT_TOKENS.
- A read of CMS source code files fails
- Source-code file endpoints return raw files and fail through the read tool. Ask for blog posts or other JSON resources instead.
- Claude says a subscription is required
- The HubSpot tools need an active Ryze AI plan or free trial. Start the trial in Ryze AI and retry.
Frequently asked questions
How do I connect Claude Code to HubSpot?
Link HubSpot to a Ryze AI workspace first. Then register the URL with claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp, open /mcp in Claude Code, select ryze and finish on the Ryze AI page by choosing the workspace and clicking Allow connection.
Does HubSpot have its own MCP server for Claude Code?
HubSpot runs a remote MCP server at https://mcp.hubspot.com with 40+ tools. You create an MCP connector in HubSpot under Development, MCP Connectors, and the server requires OAuth 2.1 with PKCE. Anthropic's Claude Code docs show a HubSpot server at https://mcp.hubspot.com/anthropic in a user-scope example. The Ryze AI connector is a separate route with 5 HubSpot tools.
Which HubSpot connector should I use with Claude Code?
Ryze AI is the best HubSpot connector for Claude Code when you want a HubSpot sign-in handled for you and one URL that also carries your other connected platforms, but it has 5 tools and needs a Ryze AI plan. HubSpot's own server needs no Ryze AI plan and covers many more HubSpot objects.
Which Claude plan do I need for Claude Code?
A Pro, Max, Ultra, Team, Enterprise or Console account, according to Anthropic. Free claude.ai accounts are excluded, though Bedrock, Google Cloud's Agent Platform and Microsoft Foundry are alternative providers.
What HubSpot permissions do I need?
You need to be a Super Admin or have App Marketplace Access in HubSpot; otherwise a Super Admin has to connect it. The portal must also include every scope the app requires, or HubSpot shows an error during install.
Should I use OAuth or an API key?
OAuth is the easier path when you sit at the terminal. Pick an API key for unattended scripts, since claude -p and Agent SDK runs cannot complete a browser sign-in. The key comes from Workspace Settings, Profile, API keys in Ryze AI, works at /mcp only and has nothing to do with your HubSpot login.
Can Claude Code edit or delete HubSpot records?
Yes. The connector has a write tool for contacts, companies, deals and blog posts and a delete tool that archives records by ID. Most CRM deletes go to HubSpot's recycling bin; deleted blog posts may not be recoverable. Set write and delete tools to ask first in Claude Code if you want to approve each change.
Can I connect more than one HubSpot portal?
Yes. Click View on the HubSpot card in Ryze AI and choose Add one more account. The starred portal is the primary that is used unless you name another, and the tools accept an optional connection_id.
What does the claude mcp add scope change?
It decides who sees the server. Local, the default, limits it to the project you are in. User makes it available everywhere on your machine. Project writes .mcp.json for your team, and each teammate approves it interactively.
Why do the HubSpot tools not show up?
Open a fresh session and check /mcp for the server status. A connector registered before you linked HubSpot in Ryze AI needs to be removed and added again. A missing claude.ai connector usually means Claude Code is signed in some other way than a claude.ai subscription.
How much does it cost?
Connecting the connector is free, but the HubSpot tools need an active Ryze AI plan or free trial. Paid Ads is $89 per month with a 7-day free trial, SEO Starter is $129 per month with a 3-day free trial and Agency is $279 per month. Annual billing takes 30% off the first year.