Edit Your Shopify Theme With Git, Claude Code and MCP: Build Sections, Pages and Blog Posts From Your IDE

Most Shopify theme changes still happen the slow way: someone opens the online code editor, edits a Liquid file, clicks save, and hopes nothing broke on the live store. There is no history, no review, and no easy undo.

There is a better workflow. Connect your theme to GitHub, open it in your IDE with Claude Code, and give Claude the Shopify Dev MCP so it can look up Shopify's documentation and validate its own work. You describe what you want, such as "add a testimonials section" or "create a landing page template", and Claude writes the code. Git records every change, and Shopify syncs it to your theme.

This guide walks through the full setup, then shows how to build a new section, a page template, and finally real pages and blog posts, all from your editor.

How the Pieces Fit Together

• Shopify CLI pulls your theme to your computer and runs a live preview with hot reload.
• Git and GitHub keep the full history of your theme, and let you review changes before they reach customers.
• Shopify's GitHub integration connects a theme in your store to a branch. Commits to the branch update the theme, and edits made in the theme editor are committed back to the branch.
• Claude Code is an AI coding assistant that runs in your terminal or inside VS Code and JetBrains IDEs. It reads your theme files, makes edits, and runs commands with your approval.
• MCP (Model Context Protocol) is an open standard for connecting AI assistants to tools. The Shopify Dev MCP gives Claude access to Shopify's documentation, API schemas and validators, so it checks its work against the real platform instead of guessing.

The result: Claude writes, the MCP validates, you review, Git records, and Shopify deploys.

What You Need

• A Shopify store, and staff or collaborator access with permission to manage themes.
• Node.js (a current LTS version), Git, and a GitHub account.
• Shopify CLI: npm install -g @shopify/cli
• VS Code or a JetBrains IDE with the Claude Code extension installed.

Step 1: Put Your Theme Under Git

Never start on your live theme. In Shopify admin, go to Online Store → Themes and use Duplicate on your current theme to make a working copy. Then pull it to your computer:

mkdir my-store-theme && cd my-store-theme
shopify theme pull --store your-store.myshopify.com
git init
git add .
git commit -m "Initial theme import"

Create an empty repository on GitHub and push to it:

git remote add origin https://github.com/your-org/my-store-theme.git
git branch -M main
git push -u origin main

Keep the theme's folders (layout, templates, sections, blocks, snippets, assets, config, locales) at the root of the repository, exactly as shopify theme pull creates them.

Step 2: Connect GitHub to Shopify

In Shopify admin, go to Online Store → Themes → Add theme → Connect from GitHub, authorise the Shopify GitHub app, and choose your repository and branch. Shopify adds a theme that stays in sync with that branch.

The sync works in both directions:

• Git to Shopify: every commit pushed to the branch updates the connected theme.
• Shopify to Git: changes made in the theme editor, such as moving sections or changing settings, are committed back to the branch by Shopify.

A simple, safe branch setup:

Step 3: Add Claude Code and the Shopify Dev MCP

Open the theme folder in your IDE and start Claude Code. Then add Shopify's official Dev MCP server to the project:

claude mcp add --scope project shopify-dev-mcp -- npx -y @shopify/dev-mcp@latest

This creates a .mcp.json file in your theme repository, so everyone on your team gets the same setup:

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

The Shopify Dev MCP gives Claude these tools:

• learn_shopify_api and search_docs_chunks: look up current Shopify documentation and API details for Liquid, the Admin API and more.
• validate_theme: run Shopify's Theme Check on the Liquid and JSON files Claude creates or edits.
• validate: check GraphQL operations against Shopify's real API schema, and report which access scopes they need.

Note what the Dev MCP does not do: it does not connect to your store or change anything in it. It is a knowledge and validation layer. That is exactly what you want from a tool that runs on every request.

Finally, add a CLAUDE.md file at the root of your theme. Claude reads it at the start of every session. Use it for your house rules, for example: "Always validate theme files with the Shopify Dev MCP. Use existing CSS classes and design settings. Never edit config/settings_data.json by hand. Add all customer-facing text to locales/en.default.json."

Step 4: Build a New Section by Describing It

Create a branch, start the live preview, and ask Claude for what you need:

git checkout -b feature/testimonials
shopify theme dev --store your-store.myshopify.com

"Create a Testimonials section with an optional heading and repeatable testimonial blocks, each with a quote and an author. Make it available in the theme editor, and follow our existing section styles."

Claude reads a few existing sections to match your theme's conventions, then writes the new file. A simplified version looks like this:

<section class="testimonials page-width">
  {%- if section.settings.heading != blank -%}
    <h2>{{ section.settings.heading | escape }}</h2>
  {%- endif -%}
  <div class="testimonials__grid">
    {%- for block in section.blocks -%}
      <blockquote {{ block.shopify_attributes }}>
        <p>{{ block.settings.quote | escape }}</p>
        <cite>{{ block.settings.author | escape }}</cite>
      </blockquote>
    {%- endfor -%}
  </div>
</section>
{% schema %}
{
  "name": "Testimonials",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "What our customers say" }
  ],
  "blocks": [
    {
      "type": "testimonial",
      "name": "Testimonial",
      "settings": [
        { "type": "textarea", "id": "quote", "label": "Quote" },
        { "type": "text", "id": "author", "label": "Author" }
      ]
    }
  ],
  "presets": [{ "name": "Testimonials", "blocks": [{ "type": "testimonial" }] }]
}
{% endschema %}

A few details make this section work well:

• The schema defines the settings and blocks your team edits in the theme editor, with no code needed.
• The presets entry makes the section appear in the theme editor's "Add section" menu.
• {{ block.shopify_attributes }} lets the theme editor highlight and select each block.

Claude then runs validate_theme through the Dev MCP. Our example above passes Shopify's Theme Check with no errors. The preview from shopify theme dev reloads as files change, so you see the result immediately.

Step 5: Create a New Page Template

Templates decide which sections appear on a type of page. Ask Claude:

"Create a landing page template that shows the page content, followed by the testimonials section with one example testimonial."

Claude creates templates/page.landing.json:

{
  "sections": {
    "main": { "type": "main-page", "settings": {} },
    "testimonials": {
      "type": "testimonials",
      "settings": { "heading": "Loved by 2,000+ customers" },
      "blocks": {
        "t1": { "type": "testimonial", "settings": { "quote": "Fast delivery and great quality.", "author": "Priya, Mumbai" } }
      },
      "block_order": ["t1"]
    }
  },
  "order": ["main", "testimonials"]
}

Any page in your store can now use this layout by choosing the landing template. Because the template is JSON, your marketing team can still rearrange its sections in the theme editor, and those changes are committed back to Git.

Step 6: Create Pages and Blog Posts From Claude

This is the part that surprises people. Pages, blogs and blog posts are store content, not theme files. They live in your Shopify admin, not in your Git repository. To create them from Claude, you use Shopify's Admin GraphQL API.

Set up API access

Create an app for your store with Admin API access, and grant only the content scopes this job needs. When the Dev MCP validates the operations below, it reports that they need write_content and write_online_store_pages, plus the matching read scopes. Put the resulting access token in a .env file that is listed in .gitignore. Never commit it.

Create a page that uses your new template

"Create an unpublished page called Diwali Sale using the landing template, with a short intro paragraph about our festive offers."

Claude writes the mutation, validates it with the Dev MCP's validate tool, and runs it with your token:

mutation CreatePage($page: PageCreateInput!) {
  pageCreate(page: $page) {
    page { id handle templateSuffix }
    userErrors { field message }
  }
}
# variables
{
  "page": {
    "title": "Diwali Sale",
    "handle": "diwali-sale",
    "body": "<p>Our biggest festive offers of the year.</p>",
    "templateSuffix": "landing",
    "isPublished": false
  }
}

Setting templateSuffix to landing connects the page to the template from Step 5. Creating it unpublished lets you review it before it goes live.

Publish a blog post

Blog posts need the ID of the blog they belong to. Claude first lists your blogs, then creates the article:

query Blogs {
  blogs(first: 10) { nodes { id title handle } }
}
mutation CreateArticle($article: ArticleCreateInput!) {
  articleCreate(article: $article) {
    article { id handle }
    userErrors { field message }
  }
}
# variables
{
  "article": {
    "blogId": "gid://shopify/Blog/123456789",
    "title": "How to Choose the Perfect Festive Gift",
    "body": "<p>...</p>",
    "summary": "Five ideas your family will actually love.",
    "author": { "name": "EyeBroadband Team" },
    "tags": ["gifting", "diwali"],
    "isPublished": false
  }
}

Because Claude can write, edit and publish content through the same conversation, you can go from "write a post about our new collection, in our brand voice, linking to these three products" to a draft in your admin within minutes. You still review it before publishing.

The Dev MCP never writes to your store itself; the writes happen only through the token you control. Community-built "Shopify admin" MCP servers also exist. If you use one, review its code and give it the smallest set of scopes it needs, because it will act on your live store.

Step 7: Review, Merge and Deploy

shopify theme check
git add sections/testimonials.liquid templates/page.landing.json locales/
git commit -m "Add testimonials section and landing page template"
git push -u origin feature/testimonials

Open a pull request into staging, check the change on the staging theme, then merge into main. Shopify's GitHub integration updates the live theme automatically. If something goes wrong, git revert undoes the change, and the theme follows.

Best Practices and Common Pitfalls

• Pull before you start. Shopify commits theme editor changes back to the branch, especially in config/settings_data.json and JSON templates. Run git pull first to avoid conflicts.
• Never let anyone, human or AI, push straight to the live branch. Use pull requests and a staging theme.
• Read every diff. Claude is fast and usually right, but you own what ships. Claude Code asks for your approval before running commands, so keep that safety net on.
• Validate everything. Ask Claude to run validate_theme after every change, and shopify theme check before every commit.
• Keep secrets out of Git. API tokens belong in .env files that are git-ignored, never in .mcp.json or CLAUDE.md.
• Prefer settings over hard-coding. Ask Claude to expose text, colours and images as section settings, so your team can change them without a developer.

Prompts to Try

• "Add an FAQ section with collapsible question and answer blocks, and output FAQ structured data."
• "Make the product page show a 'Free delivery over ₹999' badge, with the threshold as a theme setting."
• "Find every place we hard-code text in sections and move it into the locale files."
• "Run Theme Check, list the errors by severity, and fix the critical ones."
• "Create draft blog posts for our five best-selling products, each linking to the product page."

Why This Workflow Pays Off

A Git-connected theme with an AI assistant in your IDE changes how fast a store can move. New sections and landing pages take minutes instead of days. Every change is reviewed, validated against Shopify's own tooling, and can be undone with one command. Your marketing team keeps using the theme editor, while developers, and Claude, work in code with full history.

Want Help Setting This Up?

EyeBroadband sets up Git-based theme workflows, builds custom sections and Shopify apps, and trains teams to work safely with AI tools. Explore our Shopify theme development services, see our custom Shopify apps, or talk to our team.