Shopify Dev MCP Server

The Shopify Dev MCP Server (@anthropic-ai/shopify-dev-mcp) is the official MCP server built in collaboration between Shopify and Anthropic. It gives AI coding tools direct access to Shopify's developer documentation, GraphQL Admin API schema, theme validation, and more. This is the single most impactful MCP server for Shopify development.

What It Provides

The Shopify Dev MCP server does not connect to your store. Instead, it provides development intelligence -- the knowledge an AI needs to write correct Shopify code:

GraphQL schema introspection: Query the Admin API schema to discover types, fields, mutations, and their exact signatures
Developer documentation search: Search Shopify's official docs and retrieve relevant articles
Getting started guides: Access structured onboarding content for various Shopify development paths
Theme validation: Run Shopify Theme Check against your theme files
Checkout extensibility tools: Access checkout-specific documentation and patterns

No Store Access Required

This server does not need a Shopify access token or store credentials. It provides developer knowledge, not store data. For store data operations (CRUD on products, orders, etc.), you'll need the community MCP servers covered in the next section.

Installation

Claude Code

The recommended installation registers the server at the user scope, making it available across all your projects:

Install for Claude Code (global)
claude mcp add shopify-dev-mcp -s user -- npx -- -y @anthropic-ai/shopify-dev-mcp@latest

To install for a specific project only:

Install for a specific project
claude mcp add shopify-dev-mcp -- npx -- -y @anthropic-ai/shopify-dev-mcp@latest

Verify the installation:

Verify MCP servers
claude mcp list

You should see shopify-dev-mcp in the output with a stdio transport.

Cursor

Add the following to your Cursor MCP settings (.cursor/mcp.json in your project root or global settings):

.cursor/mcp.json
{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration file:

claude_desktop_config.json
{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    }
  }
}

The configuration file location varies by OS:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Codex (OpenAI)

Codex also supports MCP servers with the same configuration format:

Codex MCP configuration
{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    }
  }
}

Always Use @latest

The @latest tag ensures you get the most recent version with updated documentation and schema data. Shopify's API evolves with each quarterly release, and the MCP server is updated accordingly.

Available Tools

introspect_admin_schema

The most powerful tool in the server. It lets you query Shopify's GraphQL Admin API schema to discover types, fields, arguments, and their exact signatures.

Use cases:

Discovering available fields on a type before writing a query
Checking mutation input requirements
Finding the correct enum values for a field
Understanding type relationships (connections, edges, nodes)

Example: Discover product fields
> What fields are available on the Shopify Product type in the
  Admin API? Use the MCP schema introspection tool.

Claude Code calls introspect_admin_schema and returns the complete field list with types, descriptions, and deprecation notices.

Example: Check mutation signature
> What are the required inputs for the productCreate mutation?
  Introspect the Admin API schema.

Schema Version Awareness

The introspected schema reflects a specific API version. If you're working with an older API version, some fields or mutations may not be available. Always cross-reference with your project's target API version.

search_dev_docs

Searches Shopify's official developer documentation and returns relevant articles, guides, and API references.

Use cases:

Finding documentation for a specific Shopify feature
Looking up best practices for webhooks, authentication, or billing
Discovering new APIs or features you weren't aware of
Getting implementation guidance for complex features

Example: Search for webhook docs
> Search the Shopify developer docs for information about
  mandatory webhooks and GDPR compliance requirements.

Example: Find billing API docs
> Search Shopify docs for how to implement app billing
  with usage-based charges using the GraphQL API.

get_started

Provides structured getting-started content for different Shopify development paths. This is particularly useful when starting a new type of project.

Use cases:

Learning the setup process for a new extension type
Understanding the development workflow for Hydrogen
Getting the recommended project structure for a Remix app

Example: Get started with Functions
> Use the get_started tool to learn about building Shopify
  Functions for order discounts.

validate_theme

Runs Shopify Theme Check against your theme files, identifying issues with Liquid code, performance problems, and best practice violations.

Use cases:

Validating theme code before deployment
Finding Liquid deprecations after an API version upgrade
Identifying performance issues (missing lazy loading, large DOM)
Checking accessibility compliance

Example: Validate theme
> Validate the theme files in this project using the Shopify
  theme validation tool. Report any errors or warnings.

Combine with Claude Code's File Access

Claude Code can read your theme files AND validate them through MCP in a single workflow. Ask it to "fix all theme validation errors" and it will validate, identify issues, edit the files, and re-validate -- all autonomously.

Checkout MCP Tools

The Shopify Dev MCP includes specialized tools for checkout extensibility:

Checkout UI extension patterns: Common patterns for checkout UI extensions
Checkout validation: Validating checkout extension configurations
Payment customization: Tools for payment method filtering and customization
Delivery customization: Shipping rate modification patterns

Example: Checkout extension help
> Use the checkout MCP tools to understand how to implement
  a post-purchase upsell extension with React.

Best Practices

Use Conversation IDs

When making multiple related queries to the MCP server, the conversation context helps provide more relevant results. Claude Code handles this automatically within a session, but be aware that /clear resets this context.

Contextual follow-up queries
> Search docs for Shopify Functions
# First query establishes context

> Now show me the specific input query format for delivery customization
# Follow-up leverages conversation context for more precise results

Combine Tools for Maximum Effect

The real power emerges when you combine multiple MCP tools in a single workflow:

Combined workflow
> I need to write a GraphQL mutation to update product metafields.
  1. Introspect the Admin API schema for the metafieldsSet mutation
  2. Search the docs for metafield best practices
  3. Then write the mutation with proper TypeScript types

Claude Code will call introspect_admin_schema to get the exact mutation signature, search_dev_docs for best practices, and then synthesize both into correct, well-structured code.

OPT_OUT_INSTRUMENTATION Environment Variable

The Shopify Dev MCP server collects anonymous usage telemetry by default to improve the tool. If you want to opt out:

Opt out of telemetry
# Set environment variable before launching Claude Code
export OPT_OUT_INSTRUMENTATION=1
claude

Or add it permanently to your shell profile:

Permanent opt-out
echo 'export OPT_OUT_INSTRUMENTATION=1' >> ~/.zshrc
source ~/.zshrc

You can also configure it directly in the MCP server registration:

Register with telemetry opt-out
claude mcp add shopify-dev-mcp -s user -e OPT_OUT_INSTRUMENTATION=1 -- npx -- -y @anthropic-ai/shopify-dev-mcp@latest

Telemetry is Anonymous

The telemetry data includes only tool usage patterns (which tools are called, how often) -- not your code, prompts, or store data. It helps Shopify and Anthropic prioritize improvements to the MCP server.

Common Workflows with Shopify Dev MCP

Workflow 1: Writing a New GraphQL Query

Step-by-step
1. "Introspect the Admin API schema for the OrderConnection type"
2. "What filters are available on the orders query?"
3. "Write a paginated query to fetch orders with fulfillment status
    UNFULFILLED from the last 7 days"

Workflow 2: Building a Theme Section

Step-by-step
1. "Search docs for section schema best practices in OS 2.0"
2. "Validate the current theme for any existing issues"
3. "Create a new testimonials section following the patterns
    from the docs"
4. "Validate the theme again to ensure no new issues"

Workflow 3: Debugging an API Error

Step-by-step
1. "Search docs for error code ACCESS_DENIED on Admin API"
2. "Introspect the schema for the mutation that's failing
    to check if the required scope changed"
3. "What scopes are needed for the productUpdate mutation?"

Troubleshooting

Server Won't Start

Debug MCP server startup
# Test the server directly
npx -y @anthropic-ai/shopify-dev-mcp@latest

# Check for npm/Node issues
node --version  # Must be 18+
npm --version

# Clear npm cache if needed
npm cache clean --force

Tools Not Appearing

If you've registered the server but tools aren't showing up:

Re-register the server
# Remove and re-add
claude mcp remove shopify-dev-mcp
claude mcp add shopify-dev-mcp -s user -- npx -- -y @anthropic-ai/shopify-dev-mcp@latest

# Restart Claude Code
claude

Slow Responses

The first call after starting Claude Code may be slow because the MCP server needs to initialize (download and start the npx package). Subsequent calls within the same session are fast.

Network Required

The Shopify Dev MCP server requires network access to fetch documentation and schema data. It will not work in offline or air-gapped environments. If you're behind a corporate proxy, ensure npx can reach the npm registry and Shopify's documentation endpoints.

Next Steps

The Shopify Dev MCP server provides development knowledge. To perform actual operations on your Shopify store (creating products, managing orders, etc.), you need a store-connected MCP server. Proceed to Shopify Store MCP Servers to set up store data access.

What It Provides​

Installation​

Claude Code​

Cursor​

Claude Desktop​

Codex (OpenAI)​

Available Tools​

introspect_admin_schema​

search_dev_docs​

get_started​

validate_theme​

Checkout MCP Tools​

Best Practices​

Use Conversation IDs​

Combine Tools for Maximum Effect​

OPT_OUT_INSTRUMENTATION Environment Variable​

Common Workflows with Shopify Dev MCP​

Workflow 1: Writing a New GraphQL Query​

Workflow 2: Building a Theme Section​

Workflow 3: Debugging an API Error​

Troubleshooting​

Server Won't Start​

Tools Not Appearing​

Slow Responses​

Next Steps​

What It Provides

Installation

Claude Code

Cursor

Claude Desktop

Codex (OpenAI)

Available Tools

introspect_admin_schema

search_dev_docs

get_started

validate_theme

Checkout MCP Tools

Best Practices

Use Conversation IDs

Combine Tools for Maximum Effect

OPT_OUT_INSTRUMENTATION Environment Variable

Common Workflows with Shopify Dev MCP

Workflow 1: Writing a New GraphQL Query

Workflow 2: Building a Theme Section

Workflow 3: Debugging an API Error

Troubleshooting

Server Won't Start

Tools Not Appearing

Slow Responses

Next Steps