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

Layer	Responsibility
`src/index.ts`	Process entry, error boundary
`src/server/`	Bootstrap, MCP wiring, shutdown hooks
`src/config/`	Environment and CLI configuration
`src/lib/`	Auth, logging, Redis, shared utilities
`src/tools/`	40 MCP tools (products, orders, customers, …)

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

Category	Capabilities
Products	CRUD, variants, options, collections
Customers	CRUD, merge, address management
Orders	Query, cancel, fulfill, refund, draft orders
Metafields	Read, write, delete on any resource
Inventory	Set quantities, read levels and items
Discovery	Shop info, locations, markets, price lists
Platform	Redis token cache, structured logging, graceful shutdown, strict TypeScript

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

Variable	Required	Description
`MYSHOPIFY_DOMAIN`	Yes	Store domain, e.g. `store.myshopify.com`
`SHOPIFY_ACCESS_TOKEN`	Option A	Static `shpat_` token (legacy apps)
`SHOPIFY_CLIENT_ID`	Option B	Dev Dashboard client ID
`SHOPIFY_CLIENT_SECRET`	Option B	Dev Dashboard client secret
`SHOPIFY_API_VERSION`	No	API version (default: `2026-01`)
`LOG_LEVEL`	No	`debug`, `info`, `warn`, `error`
`REDIS_ENABLED`	No	Enable Redis persistence (`true`/`false`)
`REDIS_URL`	If Redis	Connection URL, e.g. `redis://127.0.0.1:6379`
`REDIS_KEY_PREFIX`	No	Key namespace prefix (default: `shopify-mcp:`)
`REDIS_MAX_RETRIES`	No	Max command retries (default: `10`)
`REDIS_CONNECT_TIMEOUT_MS`	No	Connect timeout in ms (default: `10000`)

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

Script	Purpose
`npm run build`	Compile TypeScript to `dist/`
`npm run typecheck`	Type-check source and tests
`npm run lint`	ESLint
`npm test`	Jest unit tests
`npm run validate`	typecheck + lint + test + build

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

Fork the repository and create a feature branch.
Run npm run validate before opening a pull request.
Keep commits focused and write clear commit messages.
Add tests for new library or configuration behavior.
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.

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.graphqlrc.ts		.graphqlrc.ts
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json

Folders and files

Latest commit

History

Repository files navigation

Shopify MCP Server

Table of Contents

Overview

Architecture

Runtime layers

Request workflow

Authentication flow

Features

Requirements

Required Admin API scopes

Installation

Run with npx (recommended)

Install from source

Claude Desktop

Configuration

Environment variables

Development

Scripts

Testing

Project Structure

Troubleshooting

Authentication errors

Wrong package installed

MCP connection issues

Redis connection failures

GraphQL userErrors

Contributing

FAQ

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages