shopify-reports-mcp

An MCP server that lets AI agents query Shopify analytics with ShopifyQL via the Admin GraphQL shopifyqlQuery endpoint. Ask your agent "show me the products with the highest margins" — it writes the ShopifyQL, runs it through this server, and interprets the results.

Tools

• query_shopify — executes a ShopifyQL query, returns { columns, rows } as JSON. Parse errors come back as error results so the agent can self-correct and retry.
• shopifyql_reference — returns the bundled ShopifyQL reference (syntax, schemas, columns, examples). Also exposed as the MCP resource shopifyql://reference.

Shopify prerequisites

1. Create an app in your organization's Dev Dashboard (the client-credentials grant only works for org-owned apps installed on stores your org owns).
2. Grant it the read_reports access scope (plus customer-data access if you want to query customer PII columns).
3. Install the app on your store and note the Client ID and Client Secret.

Access tokens are exchanged automatically and cached for their full 24-hour lifetime.

Running

Via npx (no clone needed)

Run straight from GitHub — npm clones, builds, and caches the package on first use:

# stdio mode
npx --yes github:mvacha/shopify-reports-mcp --stdio \
  --shop yourstore.myshopify.com \
  --client-id <client id> \
  --client-secret <client secret>

# HTTP mode
npx --yes github:mvacha/shopify-reports-mcp --http --port 3000

Claude Code one-liner:

claude mcp add shopify-reports -- npx --yes github:mvacha/shopify-reports-mcp --stdio \
  --shop yourstore.myshopify.com --client-id <client id> --client-secret <client secret>

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "shopifyReports": {
      "command": "npx",
      "args": [
        "--yes",
        "github:mvacha/shopify-reports-mcp",
        "--stdio",
        "--shop", "yourstore.myshopify.com",
        "--client-id", "<client id>",
        "--client-secret", "<client secret>"
      ]
    }
  }
}

HTTP mode (primary)

npm install && npm run build
node dist/index.js --http --port 3000

Clients authenticate by sending their Shopify credentials with every request:

{
  "mcpServers": {
    "shopify-reports": {
      "type": "http",
      "url": "http://your-host:3000/mcp",
      "headers": {
        "X-Shopify-Shop": "yourstore.myshopify.com",
        "X-Shopify-Client-Id": "<client id>",
        "X-Shopify-Client-Secret": "<client secret>"
      }
    }
  }
}

Or with the Claude Code CLI:

claude mcp add --transport http shopify-reports http://your-host:3000/mcp \
  --header "X-Shopify-Shop: yourstore.myshopify.com" \
  --header "X-Shopify-Client-Id: <client id>" \
  --header "X-Shopify-Client-Secret: <client secret>"

Requests without all three headers are rejected with 401. The server is stateless and multi-tenant: different clients can point it at different stores.

stdio mode (local testing)

{
  "mcpServers": {
    "shopify-reports": {
      "command": "node",
      "args": [
        "/path/to/shopify-reports-mcp/dist/index.js",
        "--stdio",
        "--shop", "yourstore.myshopify.com",
        "--client-id", "<client id>",
        "--client-secret", "<client secret>"
      ]
    }
  }
}

The SHOPIFY_SHOP, SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET environment variables work as fallbacks for the CLI flags.

Development

npm test        # vitest unit tests (mocked Shopify API)
npm run dev     # run from source with tsx
npm run build   # compile to dist/

Design doc: docs/superpowers/specs/2026-07-21-shopify-reports-mcp-design.md.