# 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.

```bash
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:

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

```bash
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:

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

Start the container:

```bash
docker compose up --build
```

Install a store by opening:

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

```bash
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](DEPLOYMENT.md) for the
operations checklist.

## License

MIT