Shopify Dev MCP Server

This project implements a Model Context Protocol (MCP) server that interacts with Shopify Dev. This protocol supports various tools to interact with different Shopify APIs. At the moment the following APIs are supported:

• Admin GraphQL API
• Functions
• (Optional) Polaris Web Components
• (Optional) Liquid/Theme validation

Setup

To run the Shopify MCP server using npx, use the following command:

npx -y @shopify/dev-mcp@latest

Usage with Cursor or Claude Desktop

Add the following configuration. For more information, read the Cursor MCP documentation or the Claude Desktop MCP guide.

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

On Windows, you might need to use this alternative configuration:

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

Disable instrumentation

In order to better understand how to improve the MCP server, this package makes instrumentation calls. In order to disable them you can set the OPT_OUT_INSTRUMENTATION environment variable. In Cursor or Claude Desktop the configuration would look like this:

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"],
      "env": {
        "OPT_OUT_INSTRUMENTATION": "true"
      }
    }
  }
}

Opt-in Polaris support (experimental)

If you want Cursor or Claude Desktop to surface Polaris Web Components documentation, include an env block with the POLARIS_UNIFIED flag in your MCP server configuration:

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"],
      "env": {
        "POLARIS_UNIFIED": "true"
      }
    }
  }
}

Opt-in Liquid/Theme validation support (experimental)

If you want Cursor or Claude Desktop to validate Liquid code and theme files, include an env block with the LIQUID flag in your MCP server configuration:

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"],
      "env": {
        "LIQUID": "true"
      }
    }
  }
}

You can also control the validation mode by setting LIQUID_VALIDATION_MODE:

• "full" (default): Enables the validate_theme tool for validating entire theme directories
• "partial": Enables the validate_theme_codeblocks tool for validating individual codeblocks

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"],
      "env": {
        "LIQUID": "true",
        "LIQUID_VALIDATION_MODE": "partial"
      }
    }
  }
}

Available tools

This MCP server provides the following tools:

Tool Name	Description
learn_shopify_api	Start here first - Teaches the LLM about supported Shopify APIs and how to use this MCP server's tools to generate valid code blocks for each API. This tool makes a request to shopify.dev to get the most up-to-date instruction for how to best work with the API the user would need to use for their prompt.
search_docs_chunks	Search across all shopify.dev documentation to find relevant chunks matching your query. Useful for getting content from many different documentation categories, but may have incomplete context due to chunking
fetch_full_docs	Retrieve complete documentation for specific paths from shopify.dev. Provides full context without chunking loss, but requires knowing the exact path. Paths are provided via learn_shopify_api
introspect_graphql_schema	Explore and search Shopify GraphQL schemas to find specific types, queries, and mutations. Returns schema elements filtered by search terms, helping developers discover available fields, operations, and data structures for building GraphQL operations
validate_graphql_codeblocks	Validate GraphQL code blocks against a specific GraphQL schema to ensure they don't contain hallucinated fields or operations
validate_theme_codeblocks	(When LIQUID=true and LIQUID_VALIDATION_MODE=partial) Validates individual Liquid codeblocks and supporting theme files (JSON, CSS, JS, SVG) to ensure correct syntax and references
validate_theme	(When LIQUID=true and LIQUID_VALIDATION_MODE=full) Validates entire theme directories using Shopify's Theme Check to detect errors in Liquid syntax, missing references, and other theme issues

Tool Usage Guidelines

When to use each documentation tool

• learn_shopify_api: Always call this first when working with Shopify APIs. It provides essential context about supported APIs and generates a conversation ID for tracking usage across tool calls.

• search_docs_chunks: Use when you need to find relevant information across multiple documentation sections or when you don't know the specific path. This tool searches through chunked content which allows for better token matching within smaller content pieces, but may miss some context from individual pages.

• fetch_full_docs: Use when you need complete documentation for a specific API resource and know the exact path (e.g., /docs/api/admin-rest/resources/product). This provides full context without any information loss from chunking.

When to use theme validation tools (requires LIQUID=true)

• validate_theme_codeblocks: Use when generating or modifying individual Liquid files or codeblocks. This tool validates syntax, checks for undefined objects/filters, and ensures references to other files exist. Perfect for incremental development and quick validation of code snippets.

• validate_theme: Use when working with complete theme directories to validate all files at once. This comprehensive validation catches cross-file issues, ensures consistency across the theme, and applies all Theme Check rules.

Available prompts

This MCP server provides the following prompts:

Prompt Name	Description
shopify_admin_graphql	Help you write GraphQL operations for the Shopify Admin API

Development

The server is built using the MCP SDK and communicates with Shopify Dev.

1. npm install
2. Modify source files
3. Run npm run build to compile or npm run build:watch to watch for changes and compile
4. Run npm run test to run tests
5. Add an MCP server that runs this command: node <absolute_path_of_project>/dist/index.js

Docker Support

You can run this MCP server in a Docker container:

Build the Docker image

Local Build

docker build -t shopify-dev-mcp .

Using Pre-built Images from GitHub Container Registry

Pre-built images are available at ghcr.io/shopify/shopify-dev-mcp:

# Pull the latest image
docker pull ghcr.io/shopify/shopify-dev-mcp:latest

# Or use a specific version
docker pull ghcr.io/shopify/shopify-dev-mcp:v1.0.0

Configure MCP to use Docker

Add this to your Cursor or Claude Desktop MCP configuration to run the server via Docker on-demand:

{
  "mcpServers": {
    "shopify-dev-mcp-docker": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/shopify/shopify-dev-mcp:latest"]
    }
  }
}

The --rm flag ensures the container is automatically removed after the MCP session ends, and -i keeps stdin open for MCP communication.

With Environment Variables

{
  "mcpServers": {
    "shopify-dev-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPT_OUT_INSTRUMENTATION=1",
        "-e",
        "POLARIS_UNIFIED=1",
        "ghcr.io/shopify/shopify-dev-mcp:latest"
      ]
    }
  }
}

Manual Docker Run

You can also run the container manually:

docker run -it --rm shopify-dev-mcp

Docker Compose (for development)

docker-compose up

License

ISC