Shopify MCP

A focused, read-only Model Context Protocol server for Shopify. It lets an assistant answer store operations questions without giving the model a general GraphQL console.

The four tools are get_shop, list_products, get_product, and list_orders. Mutations are left out deliberately: an inventory or price write deserves a separate approval-oriented design.

Two ways to run it

• Local: one store, environment credentials, and stdio transport.
• Hosted: multiple Shopify installations, OAuth, encrypted tokens, bearer-protected Streamable HTTP, cursor pagination, retries, health checks, metrics, and uninstall cleanup.

Local setup

You need Python 3.11+ and a Shopify Admin API token with read_products, read_orders, or both.

python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env

Run shopify-mcp after loading SHOPIFY_SHOP and SHOPIFY_ACCESS_TOKEN. An MCP client entry looks like this:

{
  "mcpServers": {
    "shopify": {
      "command": "/absolute/path/to/.venv/bin/shopify-mcp",
      "env": {
        "SHOPIFY_SHOP": "your-store.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_replace_me",
        "SHOPIFY_API_VERSION": "2026-07"
      }
    }
  }
}

Hosted setup

The hosted service uses Shopify OAuth. Each installation gets a separate MCP bearer token; the Shopify Admin token is encrypted at rest and never reaches the MCP client.

Generate an encryption key:

python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'

Copy .env.example to .env and set BASE_URL, SHOPIFY_CLIENT_ID, SHOPIFY_CLIENT_SECRET, TOKEN_ENCRYPTION_KEY, and DATABASE_PATH. Keep secrets in your hosting platform's secret manager rather than committing .env.

In Shopify, configure:

Callback:  https://your-host/auth/callback
Webhook:   https://your-host/webhooks/app-uninstalled

Start the container:

docker compose up --build

Install a store by opening:

https://your-host/install?shop=your-store.myshopify.com

The callback displays the MCP URL (https://your-host/mcp) and bearer token once. Reinstalling a store rotates that credential. Remote requests use Authorization: Bearer smcp_....

The OpenAI Responses API accepts the token through the remote MCP tool's authorization field. A ChatGPT custom connector may require a full interactive OAuth authorization server depending on workspace policy; this service is currently an OAuth resource server with provisioned bearer credentials, not a general-purpose authorization server.

Design

Each tool owns a fixed GraphQL query. List calls are capped at 50 records and return page_info.endCursor for the next call. The response includes Shopify throttle status.

The client applies timeouts and retries network failures, HTTP 429 responses, and 5xx responses with exponential backoff and jitter. Hosted MCP uses stateless JSON Streamable HTTP for easy horizontal transport scaling.

OAuth state is random, expires after ten minutes, and is consumed once. Callback and webhook HMACs use constant-time comparison. Expiring offline access and refresh tokens are encrypted and rotated before expiry; a per-store lock prevents concurrent use of Shopify's single-use refresh token. MCP tokens are stored only as SHA-256 digests. Uninstall webhooks remove all credentials.

The service emits JSON request logs, Prometheus-text metrics at /metrics, liveness at /healthz, and database readiness at /readyz. Restrict /metrics at the proxy or private network.

Development

pip install -e '.[dev]'
ruff check .
pytest

Tests use mock HTTP transports and temporary encrypted databases; no Shopify store is required.

Production boundary

This is a deployable single-node production baseline, not a compliance certification. Before serving real merchants:

• Put it behind HTTPS, a WAF, and request-size/rate limits.
• Use a managed secret store and define encryption-key rotation procedures.
• Replace SQLite before running multiple replicas.
• Ship logs and metrics to an observability platform and configure alerts.
• Register all Shopify-required compliance webhooks and complete protected-customer-data review.
• Add an authorization server when a target MCP client cannot supply a bearer token.
• Run dependency, container, and application security scans and commission a security review.

Product variants remain limited to the first 25. See DEPLOYMENT.md for the operations checklist.

License

MIT