███████╗██╗  ██╗ ██████╗ ██████╗ ██╗███████╗██╗   ██╗    ███╗   ███╗ ██████╗██████╗ 
██╔════╝██║  ██║██╔═══██╗██╔══██╗██║██╔════╝╚██╗ ██╔╝    ████╗ ████║██╔════╝██╔══██╗
███████╗███████║██║   ██║██████╔╝██║█████╗   ╚████╔╝     ██╔████╔██║██║     ██████╔╝
╚════██║██╔══██║██║   ██║██╔═══╝ ██║██╔══╝    ╚██╔╝      ██║╚██╔╝██║██║     ██╔═══╝ 
███████║██║  ██║╚██████╔╝██║     ██║██║        ██║       ██║ ╚═╝ ██║╚██████╗██║     
╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝╚═╝        ╚═╝       ╚═╝     ╚═╝ ╚═════╝╚═╝     

Shopify MCP

A Model Context Protocol (MCP) server that connects agents to the Shopify Admin GraphQL API. Use it to browse, edit, and clean up store data via a curated set of tools.

npm: shopify-mcp
binary: shopify-mcp

Highlights

• CRUD for products, collections, orders, and customers
• Draft orders for quotes, manual orders, and B2B pricing
• Inventory and location lookups for stock workflows
• Metafields for custom data
• Metaobject entry creation and lookup for existing definitions
• URL redirects management
• OAuth login flow with local token caching
• Bulk product cleanup utilities

Prerequisites

• Node.js 18+
• A Shopify custom app (OAuth or Admin API token)

Local setup (this repo)

Use this when you want to run the MCP server from this local checkout instead of a remote deployment.

1. Install dependencies and build:

npm install
npm run build

1. Create local env config:

cp .env.example .env

Set at least:

• MYSHOPIFY_DOMAIN=your-store.myshopify.com
• SHOPIFY_ACCESS_TOKEN=shpat_xxx
• REMOTE_MCP=false

1. Start local MCP (stdio):

npm run start:local

start:local uses stdio mode. Remote mode is only enabled with --remote or REMOTE_MCP=true.

Install + run

OAuth flow (recommended)

1. Create a custom app and copy Client ID and Client Secret.
2. In App setup, set App URL and Allowed redirection URLs to:
   http://localhost:3456/callback
3. Start the OAuth flow:

npx shopify-mcp --oauth --domain=your-store.myshopify.com --clientId=xxx --clientSecret=yyy

Tokens are stored at ~/.shopify-mcp/tokens.json. After that, start the server with just the domain:

npx shopify-mcp --domain=your-store.myshopify.com

Optional: override scopes with --scopes or SHOPIFY_SCOPES.

Access token (manual)

1. Create a custom app in Shopify
2. Enable Admin API scopes:
   • read_products, write_products
   • read_customers, write_customers
   • read_orders, write_orders
   • read_draft_orders, write_draft_orders
   • read_inventory, write_inventory
   • read_locations
   • read_content, write_content
   • read_files, write_files
3. Install the app and copy the Admin API access token

Run:

shopify-mcp --accessToken=<YOUR_ACCESS_TOKEN> --domain=<YOUR_SHOP>.myshopify.com

MCP client setup

Claude Desktop (local repo build)

Build first (npm run build), then point Claude Desktop at this repo's built entrypoint:

{
  "mcpServers": {
    "shopify-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/shopify-mcp/dist/index.js",
        "--domain",
        "your-store.myshopify.com"
      ],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxx",
        "REMOTE_MCP": "false"
      }
    }
  }
}

If you completed OAuth locally, remove SHOPIFY_ACCESS_TOKEN and keep --domain.

Claude Desktop (npm package)

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": [
        "shopify-mcp",
        "--accessToken",
        "<YOUR_ACCESS_TOKEN>",
        "--domain",
        "<YOUR_SHOP>.myshopify.com"
      ]
    }
  }
}

If you completed OAuth, omit --accessToken and keep --domain.

Config paths:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Remote MCP (Railway, etc.)

By default this server runs as a local stdio MCP. Passing --remote (or setting
REMOTE_MCP=true) switches it to HTTP/SSE mode so it can be deployed as a remote
MCP server for Claude.ai or other remote clients. This repo ships a Dockerfile
and railway.json so Railway builds and starts it in remote mode out of the box.

1. Get a token locally (one-time):

npx shopify-mcp --oauth --domain=your-store.myshopify.com --clientId=xxx --clientSecret=yyy
# Token saved to ~/.shopify-mcp/tokens.json

2. Deploy to Railway:

• Create a project from this repo. Railway reads railway.json and builds the
  Dockerfile, which starts the server with --remote.
• Set the service environment variables (Railway injects PORT automatically):

SHOPIFY_ACCESS_TOKEN=shpat_xxx           # from tokens.json (or use the OAuth vars)
MYSHOPIFY_DOMAIN=your-store.myshopify.com
MCP_API_KEY=choose-a-long-random-string  # required to authenticate remote clients
# REMOTE_MCP=true is already implied by the Dockerfile's --remote flag
# PORT is injected by Railway (defaults to 3000 when run locally)

3. Connect:

• Health check: GET /health
• MCP endpoint (SSE): GET /mcp?apiKey=<MCP_API_KEY>
• Messages: POST /messages?apiKey=<MCP_API_KEY>

Auth uses the apiKey query parameter; requests without a matching
MCP_API_KEY receive 401.

Test the container locally before deploying:

docker build -t shopify-mcp .
docker run -p 3000:3000 \
  -e MYSHOPIFY_DOMAIN=your-store.myshopify.com \
  -e SHOPIFY_ACCESS_TOKEN=shpat_xxx \
  -e MCP_API_KEY=test \
  shopify-mcp
# then in another shell: curl localhost:3000/health

Environment variables (optional)

SHOPIFY_ACCESS_TOKEN=your_access_token
MYSHOPIFY_DOMAIN=your-store.myshopify.com
# Optional OAuth values:
# SHOPIFY_CLIENT_ID=your_client_id
# SHOPIFY_CLIENT_SECRET=your_client_secret
# SHOPIFY_SCOPES=comma,separated,scopes

Tool catalog

Products

• products — unified lookup/search/filter. Pass id for a single product; omit id to list/search with filters (title, status, vendor, tag, inventory, dates, hasImages, …). Supports fields: slim | standard | full | []. Page size capped at 100.
• create-product
• update-product
• delete-product
• delete-variant
• delete-product-images
• bulk-update-products
• bulk-delete-products
• count-products-by-tag
• search-taxonomy — browse Shopify's product category taxonomy

Collections

• get-collections
• manage-collection-products
• create-collection
• update-collection
• delete-collection

Customers

• get-customers (supports pagination via cursor)
• update-customer

Orders

• orders — unified lookup/list. Pass id for a single order; omit id to list with filters (customerId, status, pagination via cursor). Replaces get-orders, get-order-by-id, and get-customer-orders.
• update-order

Draft Orders

• draft-orders — unified lookup/list. Pass id for a single draft order; omit id to list with filters (status, query, pagination via cursor).
• create-draft-order
• update-draft-order
• complete-draft-order

Inventory

• get-inventory-levels
• update-inventory

Locations

• get-locations

Metafields

• get-metafields
• set-metafield (create or update)
• delete-metafield
• list-metafield-definitions — discover metafield definitions for an owner type (PRODUCT, ORDER, CUSTOMER, …)

Metaobjects

• list-metaobject-definitions
• get-metaobject-definition
• create-metaobject
• list-metaobjects
• get-metaobject

Files

• get-files — list/search files in the store
• attach-file-to-product — attach an existing media file to a product
• detach-file-from-product — remove a media file from a product
• create-file-upload-session — start a browser upload session (remote mode only)
• get-file-upload-session — check an upload session (remote mode only)

URL redirects

• get-redirects
• create-redirect
• delete-redirect

Analytics

• get-store-counts - Get all key counts in one call (products, variants, orders, customers, collections)
• get-product-issues - Audit products for problems (zero inventory, low stock, missing images, zero price)

Bulk Operations

• start-bulk-export - Start async bulk export (products, orders, customers, inventory, or custom query)
• get-bulk-operation-status - Check progress of bulk operation
• get-bulk-operation-results - Download and parse completed results (summary, sample, or full)

Server

• get-status - Report MCP server status, configured store, and connection health

Debugging

Tail Claude Desktop logs:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

License

MIT