By Ira Bodnar, Ryze AI · Updated · Connector tested November 13, 2026
Quick answer
The main way to connect Claude Code to HubSpot is the Ryze AI connector. Link your HubSpot portal to a Ryze AI workspace through HubSpot's own sign-in, register the server in your shell with claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp, then type /mcp in Claude Code, pick ryze and sign in. A fresh session can then search and edit your contacts, companies and deals.
- In Ryze AI go to Integrations, click Connect on the HubSpot card, pick the portal and approve the permissions
- In a shell, outside any Claude Code session, run the claude mcp add command
- Open Claude Code, type /mcp, choose ryze and pick Authenticate
- Tick the workspace on the Ryze AI page, click Allow connection and ask a HubSpot question
Claude Code to HubSpot at a glance
| Fact | Detail |
|---|---|
| Main way to connect | The Ryze AI connector, a hosted MCP server that Claude Code registers with one claude mcp add command |
| Server address | https://connector.get-ryze.ai/mcp, added with the HTTP transport |
| Sign-in | Two OAuth screens: HubSpot's consent screen, opened from Ryze AI, and the Ryze AI page, opened from /mcp or claude mcp login ryze. Unattended runs can send a Ryze AI API key in an Authorization header instead |
| HubSpot tools | 5. hubspot__search, hubspot__listObjects and hubspot__read fetch data, hubspot__write creates and updates, hubspot__delete archives |
| HubSpot data it covers | Contacts, companies and deals to read and edit, contact lists and owners to read, and CMS blog content. Tickets and custom objects are outside it |
| Can Claude Code change HubSpot | Yes, through the write and delete tools. Ask rules on those two tools make Claude Code stop before each change |
| Claude Code plan | Pro, Max, Ultra, Team, Enterprise or Console. The free claude.ai plan does not include Claude Code |
| HubSpot user who can connect | A Super Admin or a user with App Marketplace Access |
| Ryze AI price | Paid Ads is $89 per month with a 7-day free trial. Adding the connector costs nothing |
| HubSpot's own options for Claude Code | A GitHub repository of Claude Code plugins built on HubSpot's remote MCP server, the Agent CLI in beta, and the Developer MCP server for building apps |
| Last tested | Connector address and sign-in details on November 13, 2026, and 11 read-only HubSpot calls on November 14, 2026. The setup steps inside Claude Code were not run |
Before you start
- A Claude Code account. Anthropic's setup page lists Pro, Max, Ultra, Team, Enterprise and Console accounts, and the free claude.ai plan does not include Claude Code. A third-party provider works as well: Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry. Anthropic's MCP page asks for no further plan before you add a remote server.
- Permission to install apps in HubSpot. Your HubSpot user has to be a Super Admin or hold App Marketplace Access. Without either, ask a Super Admin to make the connection. When the portal's plan cannot grant a scope that the app requires, HubSpot ends the install with an error.
- An active Ryze AI plan or trial. Paid Ads is $89 per month and comes with a 7-day free trial. SEO Starter, $129 per month with a 3-day free trial, covers Content Plan articles published to a HubSpot blog, and Agency is $279 per month. The connector is free to add, yet the HubSpot tools only answer while a plan or trial is active.
How to connect Claude Code to HubSpot
The first two steps happen in Ryze AI and HubSpot, the next three in your terminal and browser, and the last is your first question. Every user registers the same connector address.
Connect HubSpot in Ryze AI
Sign in to Ryze AI or create an account, open Integrations and click Connect on the HubSpot card. Ryze AI hands you over to HubSpot for the authorization.
Choose the portal and approve the permissions
Log in to HubSpot, select the account (portal) Claude Code should work in and click Choose Account. Approve what HubSpot's consent screen lists, and HubSpot brings you back to Ryze AI with the connection saved. Only if you publish blog posts: click View on the HubSpot card, choose the Blog and the Author, then Save.
Register the connector in Claude Code
In a terminal, outside any running claude session, enter claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp. The name ryze is your own choice, and Claude Code uses it to label the server's tools. With no scope flag the entry stays local to the current project; --scope user makes it available in all of them. Claude Code confirms with an Added HTTP MCP server line.
Sign in from Claude Code
Start Claude Code and type /mcp. Select ryze, press Enter and choose Authenticate. From the shell, claude mcp login ryze runs the same sign-in; with --no-browser it prints the link and waits for you to paste the redirect address back, which suits an SSH session opened with ssh -t.
Allow the workspace
A Ryze AI page opens in the browser. Sign in if it asks, tick the workspace that holds your HubSpot connection and click Allow connection. Back in the shell, claude mcp get ryze tells you whether the server is connected.
Start a new session and ask your first question
Open a new session. Claude Code fetches MCP tool definitions on demand, so the HubSpot tools load once 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 commands in the terminal.
Sources: Claude Code MCP, Claude Code MCP quickstart, Claude Code setup, Ryze AI HubSpot guide. Checked November 14, 2026.
OAuth, API key and claude.ai connectors
Claude Code takes the Ryze AI connector in three ways. Choose by where the session runs and who signs in.
Terminal sign-in with OAuth
claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp --scope userThis is the route for your own machine. The scope sets where the entry lives. Local, the default, keeps it in ~/.claude.json for the current project only. User stores it in ~/.claude.json for every project. Project writes .mcp.json into the repository, so teammates get it through version control and each of them approves it once in an interactive session. A scope cannot be edited later: remove the entry and add it again under the new one.
Terminal with a Ryze AI API key
claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp --header "Authorization: Bearer rk_live_..."Make the key in Ryze AI under Workspace Settings, Profile, API keys, Create key, and copy it right away, because it is shown once. The Ryze AI help center says keys work at /mcp and not at /sse. Claude Code saves the entry without testing the key. If the server then rejects that Authorization header, the entry shows as failed and Claude Code does not switch to OAuth, so replace the key or drop the header. A key pasted with a trailing newline earns a whitespace warning in claude mcp list. 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 finish its sign-in there; the Anthropic Directory also has a Ryze AI listing with the Community label and the same address. Then log in to Claude Code with that claude.ai subscription and open /mcp, where the connector carries a marker showing it came from claude.ai. On Team and Enterprise an Owner adds the connector for the organization first. Claude Code fetches these connectors only under a claude.ai subscription login, so sessions running on ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper or a third-party provider go without them; /status names the active login.
Scripts and limits
claude -p and Agent SDK runs have no /mcp panel and cannot finish a browser sign-in. Sign in beforehand from an interactive session with /mcp or claude mcp login ryze, or give the server a Ryze AI API key. CRM lists grow long: past 10,000 tokens a tool result brings a warning, and past 25,000, the default of MAX_MCP_OUTPUT_TOKENS, Claude Code saves it to a file and leaves the file path in the conversation. A call to an HTTP server that sends no response or progress for five minutes is aborted.
Claude Code and MCP in one table
| Topic | What Anthropic's Claude Code docs say |
|---|---|
| Config files | ~/.claude.json keeps local entries under the current project and user entries under its top-level mcpServers key. Project entries live in .mcp.json at the project root. Paths such as ~/.claude/mcp.json are never read |
| Transports | HTTP, the recommended one for remote servers; SSE, deprecated; stdio for a local process; WebSocket in JSON config only |
| Sign-in | OAuth 2.0. Claude Code checks the server's protected resource metadata first and follows a WWW-Authenticate header by itself. The browser hands back to a loopback address on a random free port |
| Static credentials | --header (short form -H) when adding, a headers object in JSON, or a headersHelper command that prints headers at connect time |
| Tool approval | From version 2.1.283, interactive sessions start in auto mode when the model and settings allow it. Rules set in /permissions are checked deny first, then ask, then allow. claude -p and Agent SDK runs without a mode start in Manual mode |
| Where servers are managed | claude mcp list, get, remove, login and logout in the shell; /mcp inside a session to authenticate, reconnect or switch a server off; /mcp in the VS Code chat panel |
| One address defined twice | Claude Code connects once, local scope first, then project, user, plugin and claude.ai connector entries. /mcp lists a claude.ai connector with the same address as hidden |
| Plan | Pro, Max, Ultra, Team, Enterprise or Console. The MCP page adds no plan for remote servers |
| Admin controls | Admins can ship managed-mcp.json, hand servers to everyone with managedMcpServers, or filter with allowedMcpServers and deniedMcpServers. A server stopped this way shows Blocked by enterprise managed policy |
Sources: Claude Code MCP, Claude Code permission modes, Claude Code permissions, Claude Code managed MCP, Claude Code cloud environments, Ryze AI in the Anthropic Directory. Checked November 14, 2026.
Claude web, ChatGPT and Cursor
Other MCP clients take the same address. HubSpot stays connected once in Ryze AI, so nothing changes on the HubSpot side.
Claude on the web and Desktop
In Customize, Connectors choose Add, then Add custom connector, call it Ryze AI and paste https://connector.get-ryze.ai/mcp. A connector added there also turns up in Claude Code when Claude Code runs on the same subscription login. The Claude guide for HubSpot has every click.
ChatGPT
OpenAI gives full custom MCP server support to Business and Enterprise/Edu workspaces on the web, and read and fetch permissions only to Pro. Add the address as a custom MCP server with OAuth. The ChatGPT guide for HubSpot walks through it.
Cursor
Put the entry below in ~/.cursor/mcp.json for all projects or in .cursor/mcp.json for one. Cursor runs the OAuth sign-in with PKCE and by default asks before it uses an MCP tool. See the Cursor guide for HubSpot.
{ "mcpServers": { "ryze": { "url": "https://connector.get-ryze.ai/mcp" } } }HubSpot permissions and scopes
HubSpot treats the Ryze AI connection as an ordinary OAuth app install. Three things set how far Claude Code reaches.
- Who can connect
- Super Admins and users with App Marketplace Access may install the app. If the portal's plan cannot grant a scope the app requires, HubSpot stops the install with an error.
- Which portal
- A connection points at one HubSpot portal, and HubSpot asks you to pick one when your login reaches several. In Ryze AI, View, Add one more account adds further portals to the same workspace. The starred portal is the primary; the tools use it unless you name another or pass a connection_id.
- What the token covers
- HubSpot's OAuth guide says an access token carries the scopes the app asked for and ignores the installing user's own record limits. Its example: a user who sees only their own contacts but approves the contacts read scope hands the app a token that reads every contact. Choose a login whose reach you are happy to share.
Scopes behind each action
Ryze AI's help center lists what its agent does once HubSpot is linked. Each action below sits next to the matching name in HubSpot's scope reference, so you can hold it against the consent screen, which keeps the exact list. The tool descriptions mention custom objects, yet no custom-object scope is requested, so leave them out of your plans.
| 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) |
The full access of the Ryze AI connection
Ryze AI's HubSpot app asks for eight required parts of access and four optional ones. Below, each part sits next to the entry HubSpot's scope reference gives for it and the HubSpot accounts that can grant it. These are reference names matched to Ryze AI's description, not strings read out of the installed app, so the consent screen remains the exact list. The Ryze AI listing in the HubSpot Marketplace shares eight kinds of data that line up with the required parts: contacts, contact properties, companies, deals, deal properties, contact lists, owners and CMS blog posts.
| Access in Ryze AI | HubSpot scope entry | What HubSpot says it covers | Available on |
|---|---|---|---|
| Contacts, read and write (required) | crm.objects.contacts.read, crm.objects.contacts.write | Contact details, and creating, changing or deleting contacts | All accounts |
| Companies, read and write (required) | crm.objects.companies.read, crm.objects.companies.write | Company properties, and creating, changing or deleting companies | All accounts |
| Deals, read and write (required) | crm.objects.deals.read, crm.objects.deals.write | Deal details, and creating, changing or deleting deals | All accounts |
| Owners, read (required) | crm.objects.owners.read | The users assigned to CRM records | All accounts |
| Contact schema, read (required) | crm.schemas.contacts.read | The property settings for contacts | All accounts |
| Deal schema, read and write (required) | crm.schemas.deals.read, crm.schemas.deals.write | The property settings for deals, to view and to change | All accounts |
| Lists, read (required) | crm.lists.read | Contact list details | All accounts |
| Content (required) | content | HubSpot's content APIs, website pages, landing pages and blogs among them | CMS Hub or Marketing Hub, Professional or Enterprise |
| Files (optional) | files | The file manager, through a legacy scope that HubSpot asks existing apps to swap for granular ones such as files.read | All accounts |
| CMS functions (optional) | cms.functions.read, cms.functions.write | Serverless functions and secrets in Content Hub | Content Hub Enterprise |
| Knowledge base (optional) | cms.knowledge_base.articles.read and related entries | Knowledge articles through the GraphQL API | Service Hub Professional or Enterprise |
| Membership (optional) | cms.membership.access_groups.read, cms.membership.access_groups.write | Membership access groups | Service Hub or Content Hub, Professional or Enterprise |
At install time HubSpot handles the two groups apart. A required scope the chosen account cannot grant stops the install with an error, while an optional scope the account lacks is dropped from the request automatically. No test checked whether a portal below CMS Hub or Marketing Hub Professional can finish the Ryze AI install.
Not requested: ticket scopes, custom object scopes (Enterprise-only entries in HubSpot's list), list editing through crm.lists.write, company property settings (crm.schemas.companies.read) and the Sensitive Data scopes. A ticket search through the Ryze AI connection was refused in the November 14, 2026 test. For tickets or custom objects from Claude Code, the HubSpot Agent CLI and HubSpot's remote MCP server both list them.
Sources: Ryze AI HubSpot guide, HubSpot scope reference, HubSpot OAuth guide, HubSpot app installs, Ryze AI in the HubSpot Marketplace. Checked November 14, 2026.
Removing access
To end access from HubSpot, open Settings, Integrations, Connected Apps, choose Actions on the app, then Uninstall, and type uninstall to confirm. In Ryze AI, View on the HubSpot card has a trash icon for each portal. In Claude Code, claude mcp logout ryze clears the stored sign-in and claude mcp remove ryze deletes the entry. Run them in that order: remove on its own deletes the local tokens without revoking them at the server.
What Claude Code can do in HubSpot
Five HubSpot tools come with the Ryze AI connector: three that read, one that writes and one that deletes. Every tool takes the workspace and an optional connection_id, and acts as the portal you connected.
| Tool | Type | What it does |
|---|---|---|
| hubspot__listObjects | Read | Pages through the records of one object type, up to 100 per call, with the properties you pick and the IDs of linked records. |
| hubspot__search | Read | Queries contacts, companies or deals through HubSpot's CRM Search API with filter groups, sorting, a text query and chosen properties, up to 200 results per page. |
| hubspot__read | Read | Sends a GET request to a HubSpot JSON resource by its path, for example one record, property definitions, owners, a list or blog posts. |
| hubspot__write | Write | Creates or updates a contact, company, deal or blog post and links records through associations, with the methods CREATE and UPDATE. |
| hubspot__delete | Delete | Archives a resource by ID, such as a CRM record or a blog post. Most CRM deletes land in HubSpot's recycling bin; a deleted blog post may be gone for good. |
Claude Code decides call by call whether to ask you. Interactive sessions on version 2.1.283 or later start in auto mode when the session supports it: a call that matches an allow, ask or deny rule follows that rule, and other MCP calls go to a second model, the classifier, instead of to you. To be asked before every HubSpot change, add ask rules for the write and delete tools in /permissions. Rule names follow the pattern mcp__<server>__<tool>, with the name you gave the server in place of <server> and the full tool name, such as hubspot__write, after it. In claude -p and Agent SDK runs, a call that needs approval is denied unless a rule or hook allows it. The Ryze AI chat has a separate Tool approvals setting that starts on Skip all approvals; pick Approve write & delete or Manual approve there. Ryze AI scheduled tasks have no approval step. On claude.ai, Customize, Connectors, Ryze AI, Tool permissions can mark write and delete tools as Needs approval.
Limits in numbers
| Limit | Number | Set by |
|---|---|---|
| Search page | 10 records unless a limit is given, 200 at most. A limit of 201 was refused in the test | HubSpot CRM Search API |
| Search total | 10,000 results per query. Paging past that returns a 400 error | HubSpot CRM Search API |
| Search filters | 5 filter groups with up to 6 filters each, 18 filters in all | HubSpot CRM Search API |
| Search rate | 5 requests per second for each account. Search responses carry none of the rate limit headers | HubSpot |
| Search query text | 3,000 characters | HubSpot CRM Search API |
| Burst limit for Marketplace OAuth apps | 110 requests every 10 seconds for each account that installs such an app, searches excluded, then a 429 error. HubSpot's page does not name Ryze AI, and no response in the test carried a rate limit header | HubSpot |
| List page | 100 records per hubspot__listObjects call, which is also the most contacts HubSpot returns in one request | Ryze AI tool definition and HubSpot |
| Batch operations | 100 records at a time | HubSpot |
| Path length | 2,048 characters for the path given to read, write and delete | Ryze AI tool definitions |
| Access token | 30 minutes, after which the app renews it with the refresh token | HubSpot |
| Recycling bin | Deleted records can be restored for up to 90 days | HubSpot |
| Tool result in Claude Code | A warning above 10,000 tokens. Above 25,000 the result is saved to a file, and MAX_MCP_OUTPUT_TOKENS moves that line. Text over 50,000 characters goes to a file whatever its token count | Claude Code |
| Idle tool call in Claude Code | Aborted after 5 minutes with no response or progress from an HTTP server. CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT changes it | Claude Code |
Sources: HubSpot CRM search, HubSpot usage guidelines, HubSpot contacts API, HubSpot OAuth tokens, HubSpot deleted records, Claude Code MCP. Checked November 14, 2026.
What the default connection returned, tested
These 11 calls ran on November 14, 2026, from a Claude Code session that already reached the Ryze AI connector, against a HubSpot portal linked through the default connection. All of them were reads. Search filters were built to match nothing and IDs were invented, so no record from the portal shows up below.
| Object or path | Tool and what was sent | Outcome |
|---|---|---|
| Contacts | hubspot__search, email EQ a random 20-letter string | Accepted. Empty answer: {"total":0,"results":[]} |
| Companies | hubspot__search, domain EQ a random 20-letter string | Accepted, with the same empty answer |
| Deals | hubspot__search, dealname EQ a random 20-letter string | Accepted, with the same empty answer |
| Contacts, one page | hubspot__listObjects, limit 1, property hs_object_id | Accepted. One result with id, properties, createdAt, updatedAt, archived and url, and a paging.next block with after and link. HubSpot also sent createdate and lastmodifieddate unasked |
| Contacts, unknown property | hubspot__search filtering on a property name that does not exist | Rejected with Error 400 |
| Contacts, oversized page | hubspot__search, limit 201, with a filter that cannot match | Rejected with Error 400, category VALIDATION_ERROR |
| Tickets | hubspot__search with a filter that cannot match | Rejected with the status not_allowed |
| crm/v3/objects/deals/0 | hubspot__read | The status not_found |
| A contact by an invented 18-digit ID | hubspot__read on crm/v3/objects/contacts/ | The status not_found, after HubSpot replied with an HTML 404 page |
| A blog post by an invented 18-digit ID | hubspot__read on cms/v3/blogs/posts/ | The status not_found, in the same HTML 404 form |
| cms/v3/blogs/posts/1 | hubspot__read | The status not_found once more. The two blog reads do not show whether blog reads work on that portal |
First 3 prompts to run
Unless a request names fields, HubSpot sends back a default set of properties, so every prompt below spells out the fields it needs. For a deal search that default set is dealname, amount, closedate, pipeline, dealstage, createdate, hs_lastmodifieddate and hs_object_id. Answers come from your own portal, which is why this page describes them instead of printing 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 on crm/v3/owners
What comes back: One row per open deal with the fields you named, and each owner's name looked up from the owners data in your portal.
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: A row for each new contact with the requested properties and the IDs of the companies linked to it.
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 present values first, then a request for your go-ahead. The update runs after you reply. Whether Claude Code also shows its own permission prompt for the write depends on your permission mode and rules.
Archiving has a tool of its own, so name the object and the record ID when you want something removed, and keep ask rules on the write and delete tools as set out above. The Ryze AI help center says the agent deletes records or blog posts when it is explicitly asked to.
10 jobs to hand to Claude Code
Ten HubSpot jobs for Claude Code, with the tool each one calls and whether the default Ryze AI connection handles it. In the November 14, 2026 test, searches and one list call came back with valid results for inputs that matched nothing or a single record, and the read tool was sent only IDs that do not exist. Owner reads, property reads, writes and deletes were not run.
| Job | Ask Claude Code | Tool | Default connection |
|---|---|---|---|
| Find one contact | Find the HubSpot contact with this email and show their lifecycle stage, owner and create date. | hubspot__search | Yes |
| Recent deals | List the deals created in the last 30 days with name, amount and stage. | hubspot__search | Yes |
| Stalled deals | Show the open deals with no change in 30 days and the owner of each one. | hubspot__search, then hubspot__read on crm/v3/owners | Yes. The owners read was not tested |
| Company overview | Look up the company on this domain and list the contacts and deals associated with it. | hubspot__search, then hubspot__listObjects with associations | Yes. Associations were not requested in the test |
| Contact export | Page through every contact with lifecycle stage and create date and save the rows to a CSV file in this folder. | hubspot__listObjects | Yes |
| Property names | List the internal names of my contact properties before we build a filter. | hubspot__read on crm/v3/properties/contacts | Yes. Not run in the test |
| New deal | Create a deal for this company, associate it with the company and its main contact, then show the record. | hubspot__write | Yes. Not run, because it changes the portal |
| Field update | Change this company's industry to the value I give you and read it back afterwards. | hubspot__write with UPDATE, then hubspot__read | Yes. Not run |
| Duplicate contact | Delete the contact with this ID. | hubspot__delete | Yes. Most CRM deletes can be restored for up to 90 days. Not run |
| Ticket list | List the open tickets for this company. | hubspot__search | No. A ticket search returned not_allowed in the test |
7 ways to connect Claude Code to HubSpot
Seven ways reach HubSpot from Claude Code, counting only those whose makers name Claude Code or accept any MCP client. This guide uses the first, the Ryze AI connector, as the main way: HubSpot is approved once in Ryze AI, Claude Code gets a single claude mcp add command, and reads, writes and deletes stay in separate tools. The other six were read on their own pages on November 14, 2026, and none was installed for this guide.
| Way | Runs where | Setup in Claude Code | What it reaches in HubSpot | Price |
|---|---|---|---|---|
| Ryze AI connector (the main way) | Hosted by Ryze AI, one address for every user | claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp, then Authenticate in /mcp. A Ryze AI API key passed with --header, or the connector from your claude.ai account, work too | Contacts, companies and deals to read, create, update and archive; contact lists and owners to read; CMS blog content. Several portals per workspace. No tickets, custom objects or list editing | Paid Ads is $89 per month with a 7-day free trial. The connector is free to add |
| HubSpot plugins for Claude Code | A plugin in Claude Code. Its tools run on HubSpot's remote MCP server | HubSpot's README gives /install-plugin https://github.com/HubSpot/hubspot-mcp-plugins and a choice of plugin. Anthropic's docs install marketplace plugins with /plugin install <name>@<marketplace> | HubSpot Sales for contacts, deals and onboarding workflows, and HubSpot Partner for Solutions Partner client records. The README lists no tools | No price stated. Apache-2.0 licence |
| HubSpot Agent CLI (beta) | A hubspot program on your computer that an agent such as Claude Code runs as a command | Install it with HubSpot's script, sign in with hubspot auth login in the browser, then add the skills with npx skills add hubspot/agent-cli-skills. HubSpot's guide names Claude Code among the agents it is built for | Contacts, companies, deals, tickets, custom objects, workflows, pipelines, properties and associations under your own HubSpot permissions, with a dry-run preview of each change. Some operations need a service key during the beta | No price stated. Beta, under HubSpot's Developer Beta Terms |
| HubSpot remote MCP server | Hosted by HubSpot at https://mcp.hubspot.com | Create an MCP connector in HubSpot under Development, MCP Connectors for a client ID and secret. The setup page has no Claude Code steps and accepts any client with OAuth and PKCE. Claude Code takes such credentials with --client-id, --client-secret and --callback-port on claude mcp add | 36 documented tools for CRM records, activities, campaigns, pages and blog posts, within what your HubSpot user may do. No delete tool | No price stated. Open to all HubSpot accounts since April 13, 2026 |
| HubSpot Developer MCP server | On your computer, under the server name HubSpotDev | Install the HubSpot CLI 8.2.0 or higher with npm install -g @hubspot/cli, run hs mcp setup, select Claude Code, choose standalone mode or the global CLI, then restart Claude Code | No CRM records. 23 tools for HubSpot's developer docs, projects, builds, test accounts and CMS templates, modules and functions | No price stated |
| Composio | Hosted | Composio's HubSpot page for ChatGPT links a Claude Code guide, which was not opened for this page. The address it gives for ChatGPT, https://connect.composio.dev/mcp, is a Streamable HTTP server, the kind claude mcp add --transport http registers. HubSpot is linked through Composio's managed OAuth app | 354 tools and 2 triggers by Composio's count, batch create, update and archive included | A free plan with 10,000 tool calls a month on the pricing page. Standard is $18 per seat per month |
| Zapier MCP | Hosted | Zapier's quickstart names Claude Code among its popular clients; its Claude Code steps were not opened. You add Zapier in the client and sign in, and Zapier switches on actions for apps already connected to your Zapier account | The HubSpot actions you enable in Zapier. Zapier prints no total | 2 tasks per successful call, failed calls free. Free has 100 tasks a month; Professional starts at $19.99 per month billed annually |
HubSpot options that do not name Claude Code
- HubSpot connector for Claude. You add it in Claude under Settings, Connectors, Browse, HubSpot, Connect. It views, creates and updates CRM records and activities, at most 10 records per bulk request, and has no delete. HubSpot's article covers Claude on the web, desktop and mobile on Pro, Max, Team or Enterprise and does not mention Claude Code. Anthropic's docs say connectors on your claude.ai account load into Claude Code under a claude.ai subscription login, but that route was not tried with HubSpot's connector for this guide.
- HubSpot's connectors for ChatGPT, Gemini and Microsoft 365 Copilot. Each article names one assistant: ChatGPT, Gemini (read-only, on paid Google Workspace plans) or Microsoft 365 Copilot. None of the three names Claude Code.
- @hubspot/mcp-server, the npm beta. Its README gives setup for Claude Desktop and Cursor and links a general list of MCP clients; Claude Code is not named. It runs on a private app token, and HubSpot turned off the creation of new legacy private apps on September 28, 2026 for new accounts and on October 26, 2026 for older ones. Version 0.4.0 from June 18, 2025 is still the newest.
- Windsor.ai, Coupler.io and baryhuang/mcp-hubspot. None of their pages names Claude Code. Windsor.ai lists Claude, ChatGPT, Copilot, Gemini CLI and the Perplexity and Cursor desktop apps. Coupler.io lists Claude, ChatGPT, OpenClaw, Cursor, Perplexity, Gemini, Copilot and a custom MCP option. The open-source server's README gives a Claude Desktop config and a Smithery install for the Claude client.
Which one to pick
Ryze AI is the best way to connect Claude Code to HubSpot when you want one claude mcp add command, HubSpot approved once in Ryze AI, several portals behind one address and deletes kept in their own tool, with one caveat: tickets, custom objects and list editing are outside its access. HubSpot's own routes need no Ryze AI plan and reach more HubSpot objects. The Agent CLI works under your own HubSpot permissions and previews each change; the remote MCP server asks you to create and manage a connector with client credentials in your portal; the plugins bring that server into Claude Code, though their README lists no tools. Choose the Developer MCP server when you build HubSpot apps or CMS assets rather than work with records. Composio and Zapier fit a team that already runs other apps through them.
Sources: HubSpot plugins for Claude Code, HubSpot Agent CLI guide, HubSpot Agent CLI article, HubSpot remote MCP server, HubSpot Developer MCP setup, HubSpot connector for Claude, HubSpot connector for ChatGPT, HubSpot connector for Gemini, HubSpot Agent for Copilot, @hubspot/mcp-server on npm, HubSpot private app sunset, Composio HubSpot, Composio pricing, Zapier MCP quickstart, Zapier MCP usage, Zapier pricing, Windsor MCP, Coupler.io HubSpot MCP, baryhuang/mcp-hubspot, Claude Code plugins, Ryze AI HubSpot guide. Checked November 14, 2026.
HubSpot and Claude Code: dates that matter
| Date | What happened |
|---|---|
| May 22, 2025 | Claude Code became generally available. |
| June 18, 2025 | Anthropic announced remote MCP servers in Claude Code. Version 1.0.27 brought Streamable HTTP servers and OAuth for remote servers. |
| September 1, 2025 | HubSpot's remote MCP server entered its first public beta. |
| February 18, 2026 | Claude Code 2.1.46 began to use MCP connectors from claude.ai. |
| February 19, 2026 | HubSpot's Developer MCP server became generally available. |
| April 13, 2026 | HubSpot's remote MCP server became generally available to all HubSpot accounts, with write access and OAuth 2.1 with PKCE required. |
| June 22, 2026 | Claude Code 2.1.186 added claude mcp login and claude mcp logout, with --no-browser. |
| June 23, 2026 | HubSpot published its knowledge base article on the Agent CLI. |
| August 18, 2026 | HubSpot created its GitHub repository of plugins for Claude Code. |
| August 2026 | The Ryze AI listing joined the Anthropic Directory, by the month printed on the listing. |
| September 15, 2026 | HubSpot announced that API versions v1 to v3 and legacy apps lose support, enforced in September 2027, and that v4 support ends on March 30, 2027. |
| September 28, 2026 | Claude Code 2.1.284 made interactive terminal and VS Code sessions start in auto mode on every plan and provider. |
| October 26, 2026 | Older HubSpot accounts could no longer create new legacy private apps. New accounts had lost the option on September 28, 2026. |
Sources: Claude Code changelog, Anthropic, May 22, 2025, Anthropic, June 18, 2025, HubSpot remote MCP beta, HubSpot Developer MCP GA, HubSpot remote MCP GA, HubSpot Agent CLI article, GitHub data for HubSpot's plugins, Ryze AI in the Anthropic Directory, HubSpot API version support, HubSpot private app sunset. Checked November 14, 2026.
How this guide was tested
This page rests on a connector check run on November 13, 2026 and on 11 HubSpot reads sent through the connector on November 14, 2026: six searches, four path reads and one list.
| What was run | What came back |
|---|---|
| The address with no sign-in, November 13 | https://connector.get-ryze.ai/mcp returned HTTP 401 with a WWW-Authenticate header that points to the sign-in details. Claude Code's docs say a server answering 401 is marked as needing authentication, and that such a header is discovered without any setting. |
| The sign-in details, November 13 | Both discovery files on the host loaded, listing the authorize, token and register endpoints, the authorization code and refresh token grants, PKCE with the S256 method, and the scopes mcp:read and mcp:write. |
| Tool definitions, November 14 | All five HubSpot tools loaded by name and match the table above, with 12 search operators, the CREATE and UPDATE write methods and a path limit of 2,048 characters. |
| Searches and one list, November 14 | Contact, company and deal searches came back as valid empty results. A contact list with limit 1 returned one result and a paging cursor. |
| Calls that returned errors, November 14 | Seven in all: two searches with bad input, one ticket search and four reads of IDs that do not exist. Their messages are in the errors table. |
Not run for this page: the setup steps inside Claude Code. Nobody ran claude mcp add, the /mcp sign-in or the Allow connection page for this guide, so those steps follow Anthropic's docs as they read on November 14, 2026, and the Ryze AI help center. The 11 HubSpot calls did come from Claude Code, in a session that already reached the Ryze AI connector. hubspot__write and hubspot__delete were not run, because they change the portal. No existing record was read by ID, and owners, lists, property definitions and blog posts were not listed. Which OAuth client method Claude Code uses with the Ryze AI server was not checked either.
Claude Code and HubSpot errors and fixes
Exact error messages from the test
Claude Code shows these as the result of the tool call. Each one came back word for word in the November 14, 2026 test, with IDs and trace values replaced by a placeholder.
| Message | Cause | Next step |
|---|---|---|
| limit must be in range [0..200] (actual value: 201) | Error 400 with the category VALIDATION_ERROR. A CRM search page holds 200 records at most. | Ask for 200 or fewer per page and carry on from the after value. |
| There was a problem with the request. | Error 400 for a search on a property name HubSpot does not have. The message does not say which one. | Have Claude Code read crm/v3/properties/contacts first and filter on the internal name. |
| The scope needed for this API call isn't available for public use. If you have questions, contact support or post in our developer forum. | The status not_allowed. The default Ryze AI connection could not search tickets on the test portal. | Keep contacts, companies and deals on Ryze AI. For tickets, use the HubSpot Agent CLI or HubSpot's remote MCP server. |
| Object not found. objectId is usually positive. | The status not_found for a deal read with the ID 0. No record has it. | Search first and reuse the id the search returns. |
| [hubspot] GET crm/v3/objects/contacts/<id>: provider returned text/html;charset=iso-8859-1 (status 404) "Error 404 Not Found" (cf-ray: <trace>; server: cloudflare) | The status not_found. HubSpot answered an invented contact or blog post ID with an HTML page, and the read tool, which parses JSON only, reports the 404. | Check the ID, find the contact by email instead, or list the blog posts and take an ID from that list. |
Other problems
- HubSpot shows an error during the install
- The HubSpot user lacks Super Admin or App Marketplace Access, or the portal's plan cannot grant a required scope. Have a Super Admin connect HubSpot in Ryze AI, or grant you the permission.
- Claude Code says the server failed to connect with an API key
- When a configured Authorization header is rejected, Claude Code marks the server as failed and never falls back to OAuth. Check that the key is a current rk_live_ key and that the address ends in /mcp, or remove the server and add it again without --header.
- claude -p or an Agent SDK run cannot sign in
- Those runs have no /mcp panel, so the browser sign-in cannot happen there. Sign in first from an interactive shell with /mcp or claude mcp login ryze, or use an API key.
- The server does not load from .mcp.json
- A project server sits at Pending approval in claude mcp list until someone approves it in an interactive session. Accept the prompt when it shows; claude mcp reset-project-choices clears earlier answers.
- No HubSpot tools appear
- If the server was added before HubSpot was linked in Ryze AI, run claude mcp remove ryze, add it again and open a new session. Tool definitions load on demand, and /mcp shows the tool count next to each connected server.
- A field is missing from the results
- HubSpot returns its default properties unless the request names others. Name the exact properties in your prompt.
- The wrong HubSpot portal is connected
- One connection means one portal. Under View on the HubSpot card in Ryze AI, add the right portal with Add one more account and delete the wrong one with the trash icon.
- The HubSpot connection stopped working
- The token may have been revoked, for example when 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
- Above 10,000 tokens Claude Code warns, and above 25,000 by default it saves the result to a file and puts the file path in the conversation. Ask for fewer properties or records, or raise MAX_MCP_OUTPUT_TOKENS.
- A read of CMS source code files fails
- Source-code file endpoints return raw files, which the read tool cannot pass on. Ask for blog posts or other JSON resources.
- Claude Code says a subscription is required
- The HubSpot tools run only with an active Ryze AI plan or free trial. Start the trial in Ryze AI and try again.
Terms on this page
- MCP
- The Model Context Protocol, an open standard that lets an AI app such as Claude Code call tools on outside systems.
- Server scope in Claude Code
- Where claude mcp add saves an entry: local for one project, user for all your projects, project for a .mcp.json shared through the repository.
- Scope in HubSpot
- A permission an app requests at install time. Each one opens a set of HubSpot API endpoints and the data behind them.
- Portal
- One HubSpot account. Each Ryze AI connection points at one, and a workspace can hold several, with one starred as primary.
- Filter group
- A block of filters in a CRM search. Every filter in a group must match, and a record that matches any one group comes back.
- Auto mode
- Claude Code's starting permission mode from version 2.1.283, in which a second model, the classifier, reviews actions in your place unless a rule decides them.
- Recycling bin
- Where HubSpot keeps deleted CRM records. They can be restored for up to 90 days.
Sources: modelcontextprotocol.io, HubSpot scope reference, HubSpot CRM search, Claude Code permission modes. Checked November 14, 2026.
Frequently asked questions
How do I connect Claude Code to HubSpot?
Link HubSpot to a Ryze AI workspace through HubSpot's sign-in, then run claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp in your shell. Open /mcp in Claude Code, choose ryze and Authenticate, and on the Ryze AI page tick the workspace and click Allow connection.
Does HubSpot have its own MCP server for Claude Code?
Yes, HubSpot runs a remote MCP server at https://mcp.hubspot.com with 36 documented tools, though its setup page gives no Claude Code steps. You create an MCP connector in HubSpot under Development, MCP Connectors for a client ID and secret, and OAuth 2.1 with PKCE is required. HubSpot's plugins for Claude Code run on it. The Ryze AI connector is a separate server with 5 HubSpot tools.
Is there a HubSpot plugin for Claude Code?
Yes, HubSpot keeps a GitHub repository, HubSpot/hubspot-mcp-plugins, with two plugins for Claude Code: HubSpot Sales and HubSpot Partner. Both run on HubSpot's remote MCP server. The README installs them with /install-plugin and the repository address, and it lists no tools.
Which HubSpot connector should I use with Claude Code?
Ryze AI is the best HubSpot connector for Claude Code when you want HubSpot's sign-in handled once in Ryze AI and one address that also carries your other connected platforms, but it has 5 tools, leaves out tickets and custom objects, and needs a Ryze AI plan. HubSpot's own server and Agent CLI need no Ryze AI plan and reach more HubSpot objects.
Which Claude plan do I need for Claude Code?
Pro, Max, Ultra, Team, Enterprise or Console, according to Anthropic's setup page. The free claude.ai plan has no Claude Code, though Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry work as providers.
What HubSpot permissions do I need?
Super Admin or App Marketplace Access; without either, a Super Admin has to make the connection. The portal's plan must also grant every scope the app requires, or HubSpot ends the install with an error.
Should I use OAuth or an API key?
Use OAuth when you sit at the terminal yourself, and an API key for unattended runs, because claude -p and Agent SDK sessions cannot finish a browser sign-in. You create the key in Ryze AI under Workspace Settings, Profile, API keys; it works at /mcp only and is separate from your HubSpot login.
Can Claude Code edit or delete HubSpot records?
Yes. The write tool creates and updates contacts, companies, deals and blog posts, and the delete tool archives a record or post by ID. Most CRM deletes go to HubSpot's recycling bin, where they can be restored for up to 90 days; a deleted blog post may not come back. Add ask rules for both tools to approve each change.
Does Claude Code ask before it changes HubSpot?
It depends on your permission mode and rules. Interactive sessions on version 2.1.283 or later start in auto mode when the model and settings allow it, and there a second model reviews calls that no rule covers, so add ask rules for the write and delete tools if every change should wait for you.
Can Claude Code read HubSpot tickets through Ryze AI?
No. A ticket search through the Ryze AI connection came back not_allowed in the November 14, 2026 test, and tickets are not in the access Ryze AI documents. The HubSpot Agent CLI and HubSpot's remote MCP server both cover tickets.
Can I connect more than one HubSpot portal?
Yes. Under View on the HubSpot card in Ryze AI, choose Add one more account. The starred portal is the default, and each tool takes an optional connection_id to point at another one.
What does the claude mcp add scope change?
Who sees the server and where it is saved. Local, the default, keeps it to the current project in ~/.claude.json. User makes it available in all your projects. Project writes .mcp.json for the team, and each teammate approves it once in an interactive session.
Does the connector work in Claude Code on the web?
Only through the repository or your claude.ai account. A cloud session cannot see servers added at local or user scope, because those live in ~/.claude.json on your machine. A cloud session with one repository loads that repository's .mcp.json, and cloud threads in a project use your claude.ai connectors.
Why do the HubSpot tools not show up?
Start a new session and look at the server status in /mcp. A server registered before HubSpot was linked in Ryze AI has to be removed and added again. If a claude.ai connector is missing, Claude Code is probably signed in some other way than a claude.ai subscription; /status shows the active method.
How much does it cost?
Adding the connector costs nothing, while 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.