shopify-ai-toolkit-wrapper

Shopify AI Toolkit Wrapper

Overview

Shopify's AI Toolkit provides an official MCP (Model Context Protocol) server for developer workflows. This skill configures it for Claude Code, enabling GraphQL schema validation, Liquid template linting, and real-time Shopify documentation search without leaving your editor.

Prerequisites

• Node.js 18+ and npm/pnpm installed
• A Shopify store with a custom app or API access token
• Access scopes appropriate for your workflow (minimum: read_products, read_themes)
• Claude Code with MCP support enabled

Instructions

Step 1: MCP Configuration

Create or update .mcp.json in your project root:

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": [
        "-y",
        "@shopify/ai-toolkit-mcp"
      ],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "${SHOPIFY_ACCESS_TOKEN}",
        "SHOPIFY_STORE_URL": "https://your-store.myshopify.com"
      }
    }
  }
}

Note: The package name @shopify/ai-toolkit-mcp may change. Check shopify.dev/docs for the latest official MCP package name and configuration.

Set your environment variables:

export SHOPIFY_ACCESS_TOKEN="shpat_xxxxxxxxxxxxxxxxxxxx"
export SHOPIFY_STORE_URL="https://your-store.myshopify.com"

See references/mcp-config.md for advanced configuration and troubleshooting.

Step 2: GraphQL Schema Validation

With the MCP server running, validate GraphQL queries against your store's live schema before executing them. The MCP introspects the schema and catches:

• Deprecated fields (e.g., priceRange should be priceRangeV2)
• Type mismatches in mutation inputs (e.g., ProductInput split into ProductCreateInput/ProductUpdateInput in 2024-10)
• Missing required fields and incorrect enum values

See references/graphql-validation.md for common validation errors and deprecated field mappings.

Step 3: Liquid Template Linting

The AI Toolkit checks Liquid templates for syntax errors, deprecated filters, and performance anti-patterns:

Issue	Bad	Fix
Deprecated filter	img_url: '800x'	image_url: width: 800
Scope leak	{% include 'card' %}	{% render 'card', product: product %}
Unbounded loop	collections.all.products	Add limit: 50 or use paginate

Step 4: Documentation Search

Query Shopify's official documentation through the MCP server for up-to-date API information:

# Example MCP queries you can make:
# - "What fields are available on the Product object?"
# - "Show me the companyCreate mutation input shape"
# - "What scopes do I need for B2B operations?"
# - "What changed in the 2024-10 API version?"

This is especially useful for checking API version changes and deprecated fields without leaving your editor.

See references/workflow-integration.md for combining MCP tools with other shopify-pack skills.

Output

• MCP server configured and connected to your Shopify store
• GraphQL queries validated against live schema before execution
• Liquid templates linted for deprecated filters and anti-patterns
• Real-time documentation search available in Claude Code

Error Handling

Error	Cause	Solution
MCP connection refused	MCP server failed to start	Check Node.js version (18+), run npx @shopify/ai-toolkit-mcp manually to see errors
Invalid access token	Token expired or wrong format	Regenerate token in Shopify admin (Settings > Apps > Develop apps)
Schema introspection failed	Insufficient API scopes	Add read_products and read_themes scopes to your app
Rate limited on doc queries	Too many documentation requests	Space out queries; docs are cached after first fetch
ENOENT: .mcp.json not found	Config file missing or wrong location	Must be in project root or ~/.claude/.mcp.json for global config
Package not found	MCP package name changed	Check shopify.dev/docs for the current official package name

Examples

Validating a GraphQL Mutation Before Execution

You need to call productCreate but aren't sure which input fields changed in the latest API version. Use the MCP server to validate your query against the live schema.

See GraphQL Validation for common validation errors and deprecated field mappings.

Setting Up MCP for a Team Project

Configure the Shopify MCP server at project, user, and global levels so the entire team gets schema validation automatically.

See MCP Config for advanced configuration and troubleshooting.

Combining MCP Validation with Other Shopify Skills

Chain MCP schema validation before running mutations from other shopify-pack skills like B2B or checkout extensions.

See Workflow Integration for the combined workflow patterns.

Resources

• Shopify AI Toolkit
• MCP Server Protocol
• Shopify Admin API Reference
• Shopify Theme Liquid Reference
• Shopify App Scopes