# shopify-reports-mcp

An MCP server that lets AI agents query Shopify analytics with
[ShopifyQL](https://shopify.dev/docs/api/shopifyql) via the Admin GraphQL
[`shopifyqlQuery`](https://shopify.dev/docs/api/admin-graphql/latest/queries/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](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant)
   (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:

```sh
# 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:

```sh
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`):

```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)

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

Clients authenticate by sending their Shopify credentials with every request:

```json
{
  "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:

```sh
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)

```json
{
  "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

```sh
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`.