MCP Setup Guides

Step-by-step instructions for connecting Shopify MCP servers to every major AI coding tool. Each guide covers installation, configuration, verification, and troubleshooting.

Recommended Setup

For the best Shopify development experience, configure two MCP servers:

Shopify Dev MCP -- Documentation, API schemas, Liquid reference (no auth needed)
Shopify Store MCP -- Live store management via Admin API (requires access token)

This guide covers both.

Prerequisites

Before starting any setup, ensure you have:

Node.js 18+ -- Download from nodejs.org
npm 9+ -- Comes with Node.js
A Shopify Partner account -- Sign up free
A development store -- Create one from your Partner dashboard

Verify your Node.js installation:

node --version   # Should output v18.x.x or higher
npm --version    # Should output 9.x.x or higher
npx --version    # Should output 9.x.x or higher

Creating a Shopify Access Token

For store management MCP servers, you need an Admin API access token:

Go to your Shopify store admin
Navigate to Settings > Apps and sales channels
Click Develop apps (you may need to enable developer access first)
Click Create an app and give it a name like "MCP Integration"
Click Configure Admin API scopes
Select the scopes you need:

Scope	Purpose
`read_products`, `write_products`	Product management
`read_orders`, `write_orders`	Order management
`read_customers`, `write_customers`	Customer data
`read_inventory`, `write_inventory`	Inventory tracking
`read_fulfillments`, `write_fulfillments`	Fulfillment processing

Click Save then Install app
Copy the Admin API access token -- you will only see it once

Token Security

Never commit your access token to version control
Never share tokens in screenshots, chat, or documentation
Store tokens in environment variables or a secrets manager
Rotate tokens periodically
Use the minimum required scopes

Claude Code (Recommended)

Claude Code has the best MCP integration with built-in server management commands.

Step 1: Add the Dev MCP Server

claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

Step 2: Add a Store MCP Server

claude mcp add shopify-store \
  -e SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxx \
  -e MYSHOPIFY_DOMAIN=your-store.myshopify.com \
  -- npx -y shopify-mcp@latest

Environment Variable Alternative

Instead of passing tokens inline, you can set them in your shell profile:

# Add to ~/.zshrc or ~/.bashrc
export SHOPIFY_ACCESS_TOKEN="shpat_xxxxxxxxxxxxx"
export MYSHOPIFY_DOMAIN="your-store.myshopify.com"

Then add the server without -e flags:

claude mcp add shopify-store -- npx -y shopify-mcp@latest

The server will read from your environment automatically.

Step 3: Verify

# List configured MCP servers
claude mcp list

# Start Claude Code and test
claude

In Claude Code, try these prompts:

# Test Dev MCP
Search the Shopify docs for product creation best practices

# Test Store MCP
List the first 5 products in my store

Scope Options

# Project scope (default) - only available in this project
claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

# User scope - available in all projects
claude mcp add --scope user shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

Managing Servers

# List all servers
claude mcp list

# Remove a server
claude mcp remove shopify-dev

# View server details
claude mcp get shopify-dev

Cursor

Step 1: Locate the Configuration File

OS	Path
macOS	`~/.cursor/mcp.json`
Linux	`~/.cursor/mcp.json`
Windows	`%APPDATA%\Cursor\mcp.json`

Create the file if it does not exist.

Step 2: Add Server Configuration

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

Step 3: Restart Cursor

After saving the configuration file, fully restart Cursor (not just reload the window).

Step 4: Verify

Open the Composer panel (Cmd+I / Ctrl+I)
Look for the MCP server icon (usually a wrench or plug icon)
Click it to see available tools
Try a query: "Search Shopify docs for webhook topics"

Cursor-Specific Tips

Cursor may take 10-15 seconds to initialize MCP servers on first launch
If tools do not appear, check the Cursor output panel for MCP-related errors
Use Cursor's .cursorrules file to add Shopify-specific context alongside MCP

Claude Desktop

macOS Setup

Step 1: Open the Configuration File

# Create the config directory if needed
mkdir -p ~/Library/Application\ Support/Claude

# Open or create the config file
open -a TextEdit ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 2: Add Configuration

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Fully quit and reopen Claude Desktop.

Step 4: Verify

Look for the hammer icon in the chat input. Click it to see available MCP tools.

Windows Setup

Step 1: Open the Configuration File

# Open or create the config file
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Step 2: Add Configuration

Use the same JSON configuration as macOS above.

Step 3: Restart and Verify

Restart Claude Desktop and check for the hammer icon.

Windows-Specific Notes

Windows PATH Issues

If npx is not found on Windows, specify the full path:

{
  "mcpServers": {
    "shopify-dev": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    }
  }
}

Codex (OpenAI)

OpenAI's Codex CLI supports MCP servers for tool augmentation.

Step 1: Install Codex

npm install -g @openai/codex

Step 2: Add MCP Servers

# Add Dev MCP
codex mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

# Add Store MCP
codex mcp add shopify-store \
  -e SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxx \
  -e MYSHOPIFY_DOMAIN=your-store.myshopify.com \
  -- npx -y shopify-mcp@latest

Step 3: Verify

codex mcp list
codex  # Start Codex and test with a Shopify query

Codex-Specific Notes

Codex may handle tool calls differently than Claude-based clients
Test each tool individually before building complex workflows
Some community MCP servers may have compatibility nuances with Codex

Windsurf

Step 1: Locate Configuration

Windsurf stores MCP configuration in its settings. Open Settings (Cmd+, / Ctrl+,) and search for "MCP" or locate the MCP configuration file:

OS	Path
macOS	`~/.windsurf/mcp.json`
Linux	`~/.windsurf/mcp.json`
Windows	`%APPDATA%\Windsurf\mcp.json`

Step 2: Add Configuration

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

Step 3: Restart and Verify

Restart Windsurf and check that MCP tools appear in the AI panel.

Cline

Cline (VS Code extension) supports MCP servers through its configuration.

Step 1: Open Cline Settings

In VS Code with Cline installed:

Open the command palette (Cmd+Shift+P / Ctrl+Shift+P)
Search for "Cline: MCP Servers"
Or edit the config file directly

Configuration file location:

OS	Path
macOS	`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
Linux	`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
Windows	`%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`

Step 2: Add Configuration

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"],
      "disabled": false
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      },
      "disabled": false
    }
  }
}

Step 3: Verify

Reload VS Code (Cmd+Shift+P > "Developer: Reload Window")
Open Cline sidebar
Check the MCP server status indicator
Test with: "List my Shopify MCP tools"

Troubleshooting

"Cannot find module" Error

Error: Cannot find module '@anthropic-ai/shopify-dev-mcp'

Causes and fixes:

Node.js version too old:

node --version  # Must be 18+
# If outdated, update via nvm:
nvm install 18
nvm use 18

npx cache corrupted:

# Clear npm cache
npm cache clean --force
# Try again
npx -y @anthropic-ai/shopify-dev-mcp@latest

Network/proxy issues:

# Test npm registry access
npm ping
# If behind a proxy:
npm config set proxy http://proxy.example.com:8080

Server Starts but No Tools Appear

Check the server is running:

# Claude Code
claude mcp list
# Look for status: "connected" vs "disconnected"

Check server logs:

In Claude Desktop, check logs at:

macOS: ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\Logs\mcp*.log

Common fix: Restart the AI client completely (not just reload).

Authentication Errors

Error: 401 Unauthorized

Fixes:

Token expired or revoked: Generate a new token in Shopify admin
Wrong domain format: Use your-store.myshopify.com (not the custom domain)
Insufficient scopes: Check that your token has the required API scopes

Environment variable not set:

# Verify the variable is set
echo $SHOPIFY_ACCESS_TOKEN
# If empty, set it:
export SHOPIFY_ACCESS_TOKEN="shpat_xxxxxxxxxxxxx"

Rate Limiting

Error: 429 Too Many Requests

Shopify's Admin API has rate limits (typically 40 requests per second for standard plans). If you hit rate limits:

Slow down requests -- Avoid running bulk operations in rapid succession
Check your plan -- Shopify Plus stores have higher limits
Use bulk operations -- Some MCP servers support GraphQL bulk operations for large datasets
Monitor usage -- Check the X-Shopify-Shop-Api-Call-Limit header in responses

Slow Server Startup

MCP servers using npx download the package on first run. Subsequent runs use the npm cache.

Speed up startup:

# Pre-install the package globally
npm install -g @anthropic-ai/shopify-dev-mcp
npm install -g shopify-mcp

# Then reference the local binary instead of npx
claude mcp add shopify-dev -- shopify-dev-mcp

Multiple Stores

To connect to multiple Shopify stores, add separate MCP server entries:

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "store-production": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_prod_token",
        "MYSHOPIFY_DOMAIN": "my-store.myshopify.com"
      }
    },
    "store-staging": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_staging_token",
        "MYSHOPIFY_DOMAIN": "my-store-staging.myshopify.com"
      }
    }
  }
}

Production Safety

When connected to both production and staging stores, always specify which store you are targeting in your prompts. Consider using read-only scopes for production tokens during development.

Server Version Conflicts

If you experience unexpected behavior after an update:

# Clear npm cache and reinstall
npm cache clean --force

# Claude Code: remove and re-add
claude mcp remove shopify-dev
claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

# Pin to a specific version if needed
claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@1.2.3

Configuration Reference

Environment Variables

Variable	Used By	Description
`SHOPIFY_ACCESS_TOKEN`	Store MCP servers	Admin API access token
`MYSHOPIFY_DOMAIN`	shopify-mcp (GeLi2001)	Store domain (e.g., `store.myshopify.com`)
`SHOP_DOMAIN`	@ajackus/shopify-mcp-server	Store domain
`SHOPIFY_STOREFRONT_TOKEN`	Storefront-capable servers	Storefront API token
`COMPOSIO_API_KEY`	Composio	Composio platform key
`ADZVISER_API_KEY`	Adzviser	Adzviser platform key

Transport Types

Transport	Description	Use Case
`stdio`	Standard I/O (local process)	Default for most setups. Server runs locally.
`streamable-http`	HTTP with streaming	Remote/hosted MCP servers
`sse`	Server-Sent Events (legacy)	Older remote servers

Most community servers use stdio transport, which means the server runs as a local process managed by your AI client. No port forwarding or network configuration is needed.

Prerequisites​

Creating a Shopify Access Token​

Claude Code (Recommended)​

Step 1: Add the Dev MCP Server​

Step 2: Add a Store MCP Server​

Step 3: Verify​

Scope Options​

Managing Servers​

Cursor​

Step 1: Locate the Configuration File​

Step 2: Add Server Configuration​

Step 3: Restart Cursor​

Step 4: Verify​

Cursor-Specific Tips​

Claude Desktop​

macOS Setup​

Step 1: Open the Configuration File​

Step 2: Add Configuration​

Step 3: Restart Claude Desktop​

Step 4: Verify​

Windows Setup​

Step 1: Open the Configuration File​

Step 2: Add Configuration​

Step 3: Restart and Verify​

Windows-Specific Notes​

Codex (OpenAI)​

Step 1: Install Codex​

Step 2: Add MCP Servers​

Step 3: Verify​

Codex-Specific Notes​

Windsurf​

Step 1: Locate Configuration​

Step 2: Add Configuration​

Step 3: Restart and Verify​

Cline​

Step 1: Open Cline Settings​

Step 2: Add Configuration​

Step 3: Verify​

Troubleshooting​

"Cannot find module" Error​

Server Starts but No Tools Appear​

Authentication Errors​

Rate Limiting​

Slow Server Startup​

Multiple Stores​

Server Version Conflicts​

Configuration Reference​

Environment Variables​

Transport Types​

Prerequisites

Creating a Shopify Access Token

Claude Code (Recommended)

Step 1: Add the Dev MCP Server

Step 2: Add a Store MCP Server

Step 3: Verify

Scope Options

Managing Servers

Cursor

Step 1: Locate the Configuration File

Step 2: Add Server Configuration

Step 3: Restart Cursor

Step 4: Verify

Cursor-Specific Tips

Claude Desktop

macOS Setup

Step 1: Open the Configuration File

Step 2: Add Configuration

Step 3: Restart Claude Desktop

Step 4: Verify

Windows Setup

Step 1: Open the Configuration File

Step 2: Add Configuration

Step 3: Restart and Verify

Windows-Specific Notes

Codex (OpenAI)

Step 1: Install Codex

Step 2: Add MCP Servers

Step 3: Verify

Codex-Specific Notes

Windsurf

Step 1: Locate Configuration

Step 2: Add Configuration

Step 3: Restart and Verify

Cline

Step 1: Open Cline Settings

Step 2: Add Configuration

Step 3: Verify

Troubleshooting

"Cannot find module" Error

Server Starts but No Tools Appear

Authentication Errors

Rate Limiting

Slow Server Startup

Multiple Stores

Server Version Conflicts

Configuration Reference

Environment Variables

Transport Types