Shopify MCP Server

A production-oriented Model Context Protocol server that exposes the Shopify Admin GraphQL API to AI assistants. Connect Claude Desktop, Claude Code, or any MCP-compatible client to manage products, customers, orders, inventory, and metafields through a typed tool interface.

Overview

This server translates MCP tool calls into Shopify Admin GraphQL operations. It supports static access tokens and OAuth client-credentials (Dev Dashboard apps), optional Redis-backed token persistence, structured JSON logging, and graceful shutdown.

flowchart LR
  Client[MCP Client] -->|stdio JSON-RPC| Server[MCP Server]
  Server --> Tools[Tool Registry]
  Tools --> GraphQL[Shopify Admin GraphQL]
  Server --> Auth[OAuth Token Manager]
  Auth --> Redis[(Redis Cache)]
  Auth --> GraphQL

Architecture

Runtime layers

Request workflow

sequenceDiagram
  participant C as MCP Client
  participant M as McpServer
  participant T as Tool
  participant S as Shopify API

  C->>M: tools/call
  M->>T: execute(args)
  T->>T: Zod schema validation
  T->>S: GraphQL request
  S-->>T: Response
  T-->>M: Formatted JSON
  M-->>C: MCP content block

Authentication flow

sequenceDiagram
  participant S as Server
  participant R as Redis
  participant SH as Shopify OAuth

  S->>R: Check cached token
  alt Valid cache hit
    R-->>S: access_token
  else Cache miss
    S->>SH: client_credentials grant
    SH-->>S: access_token + expires_in
    S->>R: Store token with TTL
  end
  Note over S: Auto-refresh 5 min before expiry

Features

All list tools support cursor pagination, sorting, and Shopify search syntax filtering.

Requirements

• Node.js 18 or later
• Shopify store with a custom app and Admin API scopes
• Redis (optional) for OAuth token persistence across restarts

Required Admin API scopes

read_products, write_products, read_customers, write_customers, read_orders, write_orders (plus scopes for inventory/metafields as needed).

Installation

Run with npx (recommended)

npx shopify-mcp \
  --clientId YOUR_CLIENT_ID \
  --clientSecret YOUR_CLIENT_SECRET \
  --domain your-store.myshopify.com

Install from source

git clone https://github.com/GeLi2001/shopify-mcp.git
cd shopify-mcp
npm install
npm run build
npm start

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": [
        "shopify-mcp",
        "--clientId", "<CLIENT_ID>",
        "--clientSecret", "<CLIENT_SECRET>",
        "--domain", "<store>.myshopify.com"
      ]
    }
  }
}

Config locations:

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

Configuration

Copy .env.example to .env and fill in values:

cp .env.example .env

Environment variables

CLI flags (--accessToken, --clientId, --clientSecret, --domain, --apiVersion) override environment variables.

Development

# Install dependencies
npm install

# Run in development (TypeScript directly)
npm run dev

# Full validation pipeline
npm run validate

# GraphQL schema validation
npm run validate:graphql

Scripts

Testing

Tests live in tests/ and cover configuration parsing, logging, error utilities, and Redis token caching.

npm test

Tests use mocked Redis clients — no running Redis instance required for the test suite.

Project Structure

shopify-mcp/
├── docs/
│   └── AUDIT.md           # Internal architecture audit
├── src/
│   ├── config/            # Environment loading (Zod-validated)
│   ├── lib/               # Auth, logging, Redis, tool factory
│   │   └── redis/         # Connection manager + token cache
│   ├── server/            # Bootstrap, MCP server, shutdown
│   ├── tools/             # MCP tool implementations
│   └── index.ts           # Entry point
├── tests/                 # Unit tests
├── .env.example           # Configuration template
├── .github/workflows/     # CI (build, lint, test, typecheck)
└── package.json

Design decisions:

• Tools use a createTool() factory to eliminate duplicated GraphQL client wiring.
• Configuration is centralized in src/config/env.ts with Zod validation.
• OAuth tokens optionally persist in Redis so restarts do not force re-authentication.
• Logs are structured JSON on stderr (safe for stdio MCP transport).

Troubleshooting

Authentication errors

Authentication credentials are required

Provide either SHOPIFY_ACCESS_TOKEN or both SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET.

Wrong package installed

If you see errors referencing a different package name, verify you are running shopify-mcp (this package), not a similarly named alternative.

MCP connection issues

Check Claude Desktop MCP logs:

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

Ensure the server starts without errors:

SHOPIFY_ACCESS_TOKEN=shpat_xxx MYSHOPIFY_DOMAIN=store.myshopify.com npm start

Redis connection failures

If REDIS_ENABLED=true but Redis is unreachable, the server exits at startup. Either start Redis locally or set REDIS_ENABLED=false.

docker run -d -p 6379:6379 redis:7-alpine

GraphQL userErrors

Shopify returns field-level errors in mutation responses. The server surfaces these as Failed to <operation>: field: message.

Contributing

1. Fork the repository and create a feature branch.
2. Run npm run validate before opening a pull request.
3. Keep commits focused and write clear commit messages.
4. Add tests for new library or configuration behavior.
5. Do not commit secrets, .env, or package-lock.json.

FAQ

Does this replace the Shopify Admin UI?
No. It provides programmatic access for AI assistants via MCP.

Can I use a static access token?
Yes. Set SHOPIFY_ACCESS_TOKEN for legacy custom apps with shpat_ tokens.

Is Redis required?
No. Redis is optional and only caches OAuth tokens for client-credentials auth.

How many tools are available?
40 tools covering products, customers, orders, metafields, inventory, and store discovery.

Which API version is used?
Default 2026-01. Override with SHOPIFY_API_VERSION or --apiVersion.

Why JSON logs on stderr?
MCP uses stdout for the protocol. Logs must go to stderr to avoid corrupting the transport.

License

MIT — see LICENSE.