How to connect Claude Code to HubSpot

Approve HubSpot once in Ryze AI, register one MCP address with claude mcp add, then search, update and archive contacts, companies and deals from your terminal.

Your MCP URL
https://connector.get-ryze.ai/mcp

Paste it into claude mcp add --transport http ryze. See the steps

See pricing

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.

  1. In Ryze AI go to Integrations, click Connect on the HubSpot card, pick the portal and approve the permissions
  2. In a shell, outside any Claude Code session, run the claude mcp add command
  3. Open Claude Code, type /mcp, choose ryze and pick Authenticate
  4. Tick the workspace on the Ryze AI page, click Allow connection and ask a HubSpot question

Claude Code to HubSpot at a glance

FactDetail
Main way to connectThe Ryze AI connector, a hosted MCP server that Claude Code registers with one claude mcp add command
Server addresshttps://connector.get-ryze.ai/mcp, added with the HTTP transport
Sign-inTwo 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 tools5. hubspot__search, hubspot__listObjects and hubspot__read fetch data, hubspot__write creates and updates, hubspot__delete archives
HubSpot data it coversContacts, 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 HubSpotYes, through the write and delete tools. Ask rules on those two tools make Claude Code stop before each change
Claude Code planPro, Max, Ultra, Team, Enterprise or Console. The free claude.ai plan does not include Claude Code
HubSpot user who can connectA Super Admin or a user with App Marketplace Access
Ryze AI pricePaid Ads is $89 per month with a 7-day free trial. Adding the connector costs nothing
HubSpot's own options for Claude CodeA 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 testedConnector 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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 user

This 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

TopicWhat 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
TransportsHTTP, the recommended one for remote servers; SSE, deprecated; stdio for a local process; WebSocket in JSON config only
Sign-inOAuth 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 approvalFrom 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 managedclaude 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 twiceClaude 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
PlanPro, Max, Ultra, Team, Enterprise or Console. The MCP page adds no plan for remote servers
Admin controlsAdmins 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 AIHubSpot scope
Read and edit contactscrm.objects.contacts.read, crm.objects.contacts.write
Read and edit companiescrm.objects.companies.read, crm.objects.companies.write
Read and edit dealscrm.objects.deals.read, crm.objects.deals.write
Read contact listscrm.lists.read
Look up record ownerscrm.objects.owners.read
Read and edit CMS blog contentcontent (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 AIHubSpot scope entryWhat HubSpot says it coversAvailable on
Contacts, read and write (required)crm.objects.contacts.read, crm.objects.contacts.writeContact details, and creating, changing or deleting contactsAll accounts
Companies, read and write (required)crm.objects.companies.read, crm.objects.companies.writeCompany properties, and creating, changing or deleting companiesAll accounts
Deals, read and write (required)crm.objects.deals.read, crm.objects.deals.writeDeal details, and creating, changing or deleting dealsAll accounts
Owners, read (required)crm.objects.owners.readThe users assigned to CRM recordsAll accounts
Contact schema, read (required)crm.schemas.contacts.readThe property settings for contactsAll accounts
Deal schema, read and write (required)crm.schemas.deals.read, crm.schemas.deals.writeThe property settings for deals, to view and to changeAll accounts
Lists, read (required)crm.lists.readContact list detailsAll accounts
Content (required)contentHubSpot's content APIs, website pages, landing pages and blogs among themCMS Hub or Marketing Hub, Professional or Enterprise
Files (optional)filesThe file manager, through a legacy scope that HubSpot asks existing apps to swap for granular ones such as files.readAll accounts
CMS functions (optional)cms.functions.read, cms.functions.writeServerless functions and secrets in Content HubContent Hub Enterprise
Knowledge base (optional)cms.knowledge_base.articles.read and related entriesKnowledge articles through the GraphQL APIService Hub Professional or Enterprise
Membership (optional)cms.membership.access_groups.read, cms.membership.access_groups.writeMembership access groupsService 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.

ToolTypeWhat it does
hubspot__listObjectsReadPages through the records of one object type, up to 100 per call, with the properties you pick and the IDs of linked records.
hubspot__searchReadQueries 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__readReadSends a GET request to a HubSpot JSON resource by its path, for example one record, property definitions, owners, a list or blog posts.
hubspot__writeWriteCreates or updates a contact, company, deal or blog post and links records through associations, with the methods CREATE and UPDATE.
hubspot__deleteDeleteArchives 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

LimitNumberSet by
Search page10 records unless a limit is given, 200 at most. A limit of 201 was refused in the testHubSpot CRM Search API
Search total10,000 results per query. Paging past that returns a 400 errorHubSpot CRM Search API
Search filters5 filter groups with up to 6 filters each, 18 filters in allHubSpot CRM Search API
Search rate5 requests per second for each account. Search responses carry none of the rate limit headersHubSpot
Search query text3,000 charactersHubSpot CRM Search API
Burst limit for Marketplace OAuth apps110 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 headerHubSpot
List page100 records per hubspot__listObjects call, which is also the most contacts HubSpot returns in one requestRyze AI tool definition and HubSpot
Batch operations100 records at a timeHubSpot
Path length2,048 characters for the path given to read, write and deleteRyze AI tool definitions
Access token30 minutes, after which the app renews it with the refresh tokenHubSpot
Recycling binDeleted records can be restored for up to 90 daysHubSpot
Tool result in Claude CodeA 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 countClaude Code
Idle tool call in Claude CodeAborted after 5 minutes with no response or progress from an HTTP server. CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT changes itClaude 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 pathTool and what was sentOutcome
Contactshubspot__search, email EQ a random 20-letter stringAccepted. Empty answer: {"total":0,"results":[]}
Companieshubspot__search, domain EQ a random 20-letter stringAccepted, with the same empty answer
Dealshubspot__search, dealname EQ a random 20-letter stringAccepted, with the same empty answer
Contacts, one pagehubspot__listObjects, limit 1, property hs_object_idAccepted. 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 propertyhubspot__search filtering on a property name that does not existRejected with Error 400
Contacts, oversized pagehubspot__search, limit 201, with a filter that cannot matchRejected with Error 400, category VALIDATION_ERROR
Ticketshubspot__search with a filter that cannot matchRejected with the status not_allowed
crm/v3/objects/deals/0hubspot__readThe status not_found
A contact by an invented 18-digit IDhubspot__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 IDhubspot__read on cms/v3/blogs/posts/The status not_found, in the same HTML 404 form
cms/v3/blogs/posts/1hubspot__readThe 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.

JobAsk Claude CodeToolDefault connection
Find one contactFind the HubSpot contact with this email and show their lifecycle stage, owner and create date.hubspot__searchYes
Recent dealsList the deals created in the last 30 days with name, amount and stage.hubspot__searchYes
Stalled dealsShow the open deals with no change in 30 days and the owner of each one.hubspot__search, then hubspot__read on crm/v3/ownersYes. The owners read was not tested
Company overviewLook up the company on this domain and list the contacts and deals associated with it.hubspot__search, then hubspot__listObjects with associationsYes. Associations were not requested in the test
Contact exportPage through every contact with lifecycle stage and create date and save the rows to a CSV file in this folder.hubspot__listObjectsYes
Property namesList the internal names of my contact properties before we build a filter.hubspot__read on crm/v3/properties/contactsYes. Not run in the test
New dealCreate a deal for this company, associate it with the company and its main contact, then show the record.hubspot__writeYes. Not run, because it changes the portal
Field updateChange this company's industry to the value I give you and read it back afterwards.hubspot__write with UPDATE, then hubspot__readYes. Not run
Duplicate contactDelete the contact with this ID.hubspot__deleteYes. Most CRM deletes can be restored for up to 90 days. Not run
Ticket listList the open tickets for this company.hubspot__searchNo. 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.

WayRuns whereSetup in Claude CodeWhat it reaches in HubSpotPrice
Ryze AI connector (the main way)Hosted by Ryze AI, one address for every userclaude 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 tooContacts, 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 editingPaid Ads is $89 per month with a 7-day free trial. The connector is free to add
HubSpot plugins for Claude CodeA plugin in Claude Code. Its tools run on HubSpot's remote MCP serverHubSpot'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 toolsNo 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 commandInstall 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 forContacts, 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 betaNo price stated. Beta, under HubSpot's Developer Beta Terms
HubSpot remote MCP serverHosted by HubSpot at https://mcp.hubspot.comCreate 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 add36 documented tools for CRM records, activities, campaigns, pages and blog posts, within what your HubSpot user may do. No delete toolNo price stated. Open to all HubSpot accounts since April 13, 2026
HubSpot Developer MCP serverOn your computer, under the server name HubSpotDevInstall 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 CodeNo CRM records. 23 tools for HubSpot's developer docs, projects, builds, test accounts and CMS templates, modules and functionsNo price stated
ComposioHostedComposio'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 app354 tools and 2 triggers by Composio's count, batch create, update and archive includedA free plan with 10,000 tool calls a month on the pricing page. Standard is $18 per seat per month
Zapier MCPHostedZapier'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 accountThe HubSpot actions you enable in Zapier. Zapier prints no total2 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

DateWhat happened
May 22, 2025Claude Code became generally available.
June 18, 2025Anthropic announced remote MCP servers in Claude Code. Version 1.0.27 brought Streamable HTTP servers and OAuth for remote servers.
September 1, 2025HubSpot's remote MCP server entered its first public beta.
February 18, 2026Claude Code 2.1.46 began to use MCP connectors from claude.ai.
February 19, 2026HubSpot's Developer MCP server became generally available.
April 13, 2026HubSpot's remote MCP server became generally available to all HubSpot accounts, with write access and OAuth 2.1 with PKCE required.
June 22, 2026Claude Code 2.1.186 added claude mcp login and claude mcp logout, with --no-browser.
June 23, 2026HubSpot published its knowledge base article on the Agent CLI.
August 18, 2026HubSpot created its GitHub repository of plugins for Claude Code.
August 2026The Ryze AI listing joined the Anthropic Directory, by the month printed on the listing.
September 15, 2026HubSpot 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, 2026Claude Code 2.1.284 made interactive terminal and VS Code sessions start in auto mode on every plan and provider.
October 26, 2026Older 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 runWhat came back
The address with no sign-in, November 13https://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 13Both 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 14All 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 14Contact, 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 14Seven 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.

MessageCauseNext 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.

Connect HubSpot to Claude Code

Connect HubSpot once and use the same URL in other MCP clients. Paid Ads is $89 per month with a 7-day free trial; annual billing takes 30% off the first year.

HubSpot MCP server

Need help? Read the Ryze AI HubSpot guide or email Ryze AI support.