How to Set Up the Shopify AI Toolkit with Claude Code

Key takeaways

• The plugin method is the fastest path and auto-updates. Two commands to install.
• Manual skills installation works but doesn’t auto-update. Bundled schemas drift from the live platform over time.
• Set OPT_OUT_INSTRUMENTATION=true before your first validation if you’re working with proprietary code. Validation payloads include your code by default.
• Store operations execute immediately on your live store. There is no draft step.
• Always query current state before running mutations. The toolkit has no undo.

Claude Code is one of the primary AI coding tools supported by the Shopify AI Toolkit. Once connected, your Claude Code session gets access to current Shopify documentation, code validation against bundled API schemas, and the ability to execute store operations through the Shopify CLI.

This guide covers setup and what to know. For the full breakdown of what the toolkit does, how it works, and the governance risks around store execution, see our Shopify AI Toolkit overview.

Why you can trust us

Jacques has over 15 years of development experience and has worked with hundreds of Shopify stores. We built Fudge - an AI-native Shopify page builder and store editor with a 5.0 rating and a Built for Shopify badge. We use these tools daily.

Prerequisites

• Claude Code installed and working
• Node.js 18 or higher (node --version to check)
• Shopify CLI installed (needed for store operations)
• A Shopify store to connect to (only required for store operations - not needed for documentation search and code validation)

Installation: plugin method (recommended)

The plugin method is the fastest path and auto-updates whenever Shopify releases new capabilities.

Step 1: Install the plugin

In your Claude Code session, run these two commands:

/plugin marketplace add Shopify/shopify-ai-toolkit
/plugin install shopify-plugin@shopify-ai-toolkit

This installs all available agent skills automatically.

Step 2: Verify installation

Ask Claude something Shopify-specific to confirm the toolkit is active:

What's the correct GraphQL mutation to update a product's title in the Shopify Admin API?

If the toolkit is working, Claude will search current Shopify documentation and return a validated query rather than guessing from its training data.

Alternative: manual skills installation

If you prefer to install skills manually (e.g., you only need specific capabilities):

Install all skills

npx skills add Shopify/shopify-ai-toolkit

Install a specific skill

npx skills add Shopify/shopify-ai-toolkit --skill shopify-admin

Manually installed skills don’t auto-update. You’ll need to re-run the install command periodically to stay current with Shopify’s API changes. Over time, the bundled schemas will drift from the live platform.

Alternative: MCP server setup

For direct MCP integration, you can connect to Shopify’s Dev MCP server. This runs as a local server/client integration but makes network calls to Shopify endpoints for documentation search. Authentication depends on which MCP server you’re connecting to - Dev MCP for docs doesn’t require store auth; store operations do.

Refer to the Shopify AI Toolkit docs for configuration format and options.

Telemetry and code transmission

Before you start validating code, know this: both validate.mjs and search_docs.mjs send usage payloads to Shopify’s servers by default.

The SKILL.md files describe this as “anonymized validation results (pass/fail and skill name).” However, the actual validation payload includes the code being validated - your GraphQL queries, Liquid templates, and other code you run through the validator.

To opt out, set this environment variable:

export OPT_OUT_INSTRUMENTATION=true

If you’re working with proprietary code, client code, or anything you don’t want transmitted to Shopify’s endpoints, set this before your first validation.

Connecting to your store

To execute operations on a live store (not just generate and validate code), you need to authenticate through the Shopify CLI.

Authentication

The toolkit handles this automatically when you request a store operation, but the underlying command is:

shopify store auth --store yourstore.myshopify.com --scopes write_products,read_products

This prompts you to authorize access through the Shopify admin.

Scope selection

The toolkit’s validation script detects the minimum required OAuth scopes for each operation. Common scopes:

Stick to the minimum scopes needed. write_products gives access to ALL product write operations, not just the specific mutation you’re running.

What you can do

Validated GraphQL development

Ask Claude to write Shopify GraphQL queries and mutations. The toolkit validates them against the bundled API schema before you use them.

Claude will search current Shopify Admin API docs, generate the query, validate it against the bundled schema, and report any issues or required scopes. No more hallucinated fields or deprecated patterns.

Theme development

Work with Liquid templates with validation against Shopify’s theme rules. The toolkit validates schemas against JSON definitions and enforces LiquidDoc headers.

Related: adding custom Liquid logic in Shopify.

Hydrogen storefront development

Build headless storefronts with validated React components and correct imports from @shopify/hydrogen.

Store operations

Execute operations directly on your connected store. Claude generates the mutation, validates it, authenticates with your store, and executes it via shopify store execute --allow-mutations.

The change is live immediately. There is no draft step. See the risks section in our main guide for why this matters.

Metafield management

Extend your store’s data model with metafield definitions. The toolkit uses TOML for metafield definitions and knows the difference between app-owned and merchant-owned data.

Related: adding metafields to Shopify products.

Functions and extensions

Build backend customization - discounts, cart validation, delivery rules - and scaffold UI extensions with Polaris components. The Functions skill knows that Shopify Functions must be pure (no network calls, no filesystem, no randomness).

Related: adding custom JavaScript in Shopify.

Best practices

Always query before mutating

Before updating anything, read the current state first:

Show me the current title, description, and SEO fields for the product with handle "classic-tee"

This gives you a baseline and helps prevent unintended overwrites.

Be specific with mutations

Vague prompts lead to broad mutations. Instead of “Optimize my products for SEO,” be specific:

Update ONLY the meta description for the product with handle "classic-tee" to "Shop the Classic Tee - premium cotton, 5 colors, free shipping over $50"

Push themes as unpublished

When pushing theme changes, always push as unpublished first. The toolkit supports shopify theme push --unpublished, but doesn’t enforce it by default. Make it a habit.

One resource at a time for critical changes

For important updates, run them one product at a time rather than in bulk. This limits blast radius if something goes wrong.

Keep your own backups

The toolkit has no undo. Before running mutations that update existing content, export or note down the current values.

Limitations

These are structural to the toolkit, not Claude Code-specific. For the full risk analysis, see our Shopify AI Toolkit overview.

1. No draft mode - Store mutations execute on your live store immediately
2. No preview - You can’t see what changes will look like before they happen
3. No undo/rollback - Changes are permanent once executed
4. No audit trail - No toolkit-level record of what was changed
5. Broad scopes - OAuth permissions apply to entire resource types, not individual items
6. Code sent to Shopify - Validation payloads include your code by default (opt out with OPT_OUT_INSTRUMENTATION=true)
7. Manual skills decay - If you installed skills manually, they won’t auto-update

Quick reference

Summary

The Shopify AI Toolkit turns Claude Code into a Shopify-aware development environment. The documentation search and code validation make it worth installing for any Shopify developer - the accuracy loop alone saves time.

For development work - app building, theme creation, Hydrogen storefronts - it’s a clear productivity upgrade. For store operations, the governance gaps apply: no drafts, no preview, no undo, and code telemetry enabled by default. Be deliberate about what you enable.

For the full picture on risks and governance, read our Shopify AI Toolkit overview. For setup on other platforms, see our Cursor guide and OpenAI Codex guide.

This article was last updated in April 2026 based on the Shopify Editions Winter 2026 release.