How to use Claude Code with HubSpot CMS

Claude Code works on HubSpot CMS through the HubSpot CLI. You fetch your theme's files to your computer, Claude edits the templates, modules, CSS and JavaScript, and the CLI uploads them back to HubSpot. The catch is that HubSpot's docs say files uploaded with hs cms upload or saved under hs cms watch are "live immediately." So the safe setup is to have Claude work in a developer test account or CMS developer sandbox, preview locally, keep the code in git, and let a person deploy to your real account, ideally through HubSpot's GitHub deploy action after a reviewed pull request.

HubSpot also publishes MCP servers: a remote server that can read CRM and content data and create, edit and publish pages and blog posts, and a local Developer MCP server for building HubSpot projects. This guide covers the CLI workflow, the GitHub integration and those servers, as HubSpot documents them in October 2026.

What Claude Code can change on HubSpot

HubSpot hosts your site. HubSpot's CMS overview says you "can't alter or extend system fundamentals manually or via plugins, manipulate low-level rendering, or access and alter database content directly." What you do own is the developer layer:

HubL is HubSpot's template language. Tell Claude in CLAUDE.md that the theme uses HubL, which theme you're working on, and which modules content editors depend on. HubSpot also notes that .json theme and module files "can only be created and uploaded to a HubSpot account through the local development tools," which is another reason to keep them in git.

Setting up the HubSpot CLI with Claude Code

1. Use a test account. HubSpot recommends building in a developer test account or a CMS developer sandbox account. Point Claude's CLI at that first, not at your live portal.
2. Install the CLI. Per HubSpot's install guide, run npm install -g @hubspot/cli on Node.js 20 or higher. Check you're on the recommended 8.15.0 with hs --version.
3. Authenticate yourself. Run hs account auth and follow the prompts to create a Personal Access Key. Do this in your own terminal, not in a prompt. The CLI keeps its account config in ~/.hscli/config.yml; keep the key out of CLAUDE.md and deny Claude reads of that file.
4. Link the folder to the test account. In the theme folder, run hs account link and make the test account the folder's default. HubSpot describes this as a way "to prevent accidentally running a command against the wrong account."
5. Fetch the theme. hs cms fetch downloads files from Design Tools. It won't overwrite local files unless you add --overwrite.
6. Commit to git on a new branch, so every change is a reviewable diff.
7. Write a short CLAUDE.md naming the account to use, the theme path, and the rule that Claude never runs upload, watch or deploy commands against the production account.

Add ask rules for hs cms upload and hs cms watch in your Claude Code permission settings, so Claude Code must ask before running them. A rule in settings holds even if an instruction in the conversation is forgotten.

Why "live immediately" changes the workflow

HubSpot's CMS commands reference says of hs cms upload: "Changes uploaded through this command will be live immediately." Of hs cms watch: "Any changes made when saving will be live immediately." On a test account that's convenient. On your real account, it means a file Claude saves can change your website with no review step in between.

A few flags deserve extra care:

• --clean on upload deletes the destination folder before uploading, and HubSpot warns that global content set in the global content editor is reset to the defaults in your global partials.
• --remove on watch deletes files in HubSpot that aren't found locally. Without it, deleting a local file doesn't delete it in HubSpot, and renaming a folder uploads a new one beside the old.
• --cms-publish-mode takes draft or publish on upload and watch, and the default is publish, which is why uploads go live. HubSpot lets you set a defaultMode per account in the CLI config. A draft default on your live account is a sensible extra guard, but test how drafts behave there before relying on it.

The safe pattern is to preview locally, then deploy through review:

• Preview. hs cms theme preview renders "a live preview of your changes without uploading files to the account." HubSpot notes it may ask for your password to set up a local SSL certificate.
• Score. hs cms lighthouse-score --theme=path uses Google's Lighthouse to score templates for accessibility, performance, SEO and best practices, on desktop or mobile with --target. It's a useful check after Claude's edits; our guide to accessibility fixes with Claude Code explains why automated scores are only a start.
• Upload to the test account and check real pages there.

Deploying through GitHub instead of the CLI

HubSpot's GitHub integration guide recommends the HubSpot CMS Deploy GitHub Action, which deploys changes "from a branch to your production HubSpot account" when a pull request is merged into main. This is the workflow that fits Claude Code best:

1. Claude works on a feature branch and opens a pull request.
2. Automated checks run on the pull request. Our guide to Claude Code in GitHub Actions for website QA shows how to add review checks.
3. A person reviews the diff and the test-account result, then merges.
4. The action deploys main to production.
5. In HubSpot, go to Design Tools, right-click the theme folder and choose Lock folder, as HubSpot advises, so nobody edits the deployed files directly and drifts from git.

Protect main with required reviews, because a merge is now a deploy. One documentation conflict to know about: the GitHub guide (last modified February 2026) still tells you to run hs fetch, hs upload and hs create website-theme. The CLI reference says those older commands stopped working in version 8.0.0. Use the hs cms versions.

HubSpot's MCP servers

MCP (Model Context Protocol) lets Claude call tools in another system. HubSpot documents two servers and a newer agent tool, and they do very different jobs.

A few details from HubSpot's remote MCP server docs: all actions respect your HubSpot user permissions; the page tools ask for confirmation before creating a page, publishing or restoring a revision; and if HubSpot adds new scopes later, existing users must reinstall to grant them. The website page, blog post and preview tools carry a note that they are "only available for select AI clients (Claude, ChatGPT, and Gemini)," without saying whether Claude Code counts, so check which tools appear after you connect. Claude Code's own MCP docs use https://mcp.hubspot.com/anthropic as an example address; follow the address HubSpot's connector setup gives you. HubSpot doesn't put a beta or GA label on the remote server as a whole, though some areas, such as revenue objects and quotes, are marked beta.

HubSpot's confirmations are a good start, but add Claude Code ask rules on the page, blog and CRM write tools too, so the prompt comes from settings you control. The Developer MCP server can also deploy projects to your account, so review before anything deploys there.

HubSpot is blunt about the Agent CLI: write operations "can modify or permanently delete live data in your account," and it strongly recommends --dry-run and a sandbox account. That's CRM territory, not website building. Keep it out of website projects unless the job is specifically about CRM data. Our guide to MCP servers for website teams covers scoping these connections.

Good jobs for Claude Code on HubSpot

• Theme fixes: responsive layout bugs, CSS cleanup, template structure and heading order.
• New modules: a pricing table, an FAQ block or a testimonial slider, built as fields plus HubL, reviewed in the test account.
• Audits: read the theme for unused CSS, missing alt text fields in modules or hard-coded copy that editors can't change.
• Migrating a HubL theme to a project: HubSpot documents React + HubL projects alongside classic HubL themes, with a guide to migrate a classic theme to a project. That's a larger job worth planning carefully.

If a marketing team runs your HubSpot site, our guide to Claude Code for marketing teams covers who should do what when not everyone writes code.

Plans and access to check first

HubSpot's CMS developer docs don't clearly state which Content Hub tier you need for CLI theme work or serverless functions. Check your subscription with HubSpot before scoping a project. Some MCP features do name plans: the AEO tools need Marketing Hub Professional or Enterprise, and quotes need Revenue Hub Professional or Enterprise. Set up a test copy before any of this; our guide to setting up a staging copy explains why.

Conclusion

On HubSpot CMS, Claude Code is a strong helper for themes and modules, as long as you respect one fact: CLI uploads go live at once. Work in a developer test account or sandbox, preview with hs cms theme preview, keep the code in git, deploy through a reviewed pull request and HubSpot's GitHub action, and lock the deployed folder. Use HubSpot's MCP servers for content and project work with confirmations on, and keep the Agent CLI to CRM work on a sandbox. If you'd like a team to set this up, see our Claude Code development services, and our Claude Code templates include a starting CLAUDE.md. More guides are in our Claude Code Guide.

Frequently asked questions