# Shopify MCP Server

A **Model Context Protocol (MCP)** server that gives Claude — or any MCP-compatible AI client — six scoped tools for a Shopify store's Admin API. Ask plain-English questions about chargebacks, orders, refunds, customers, and revenue; get answers grounded in live store data.

Ships with a mock-data mode enabled by default. Clone, `pip install`, run, and see Claude answering questions end-to-end — no store or credentials required.

---

## What it does

Six tools, each a small Python function with a docstring the model reads:

| Tool | What it does |
|------|--------------|
| `get_disputes(status?, limit=25)` | List chargebacks and inquiries, optionally filtered by status |
| `chargeback_rate(days=30)` | Dispute count / order count over N days as a percentage — with a `healthy` / `watch` / `high` risk flag |
| `get_orders(status?, limit=25)` | Recent order feed, most recent first |
| `search_customers(query, limit=10)` | Lookup by email, name, or phone |
| `get_refunds(order_id?, limit=25)` | Refund history for one order or store-wide |
| `dispute_details(dispute_id)` | Full case data for a single dispute — status, reason, amount, evidence deadline |

Under the hood: standard Shopify Admin REST API against `2025-07`. No third-party integrations, no hidden state — the server holds no data, just proxies queries.

---

## Quickstart — mock mode (no store needed)

```bash
git clone https://github.com/weli-dev/shopify-mcp
cd shopify-mcp
pip install -r requirements.txt
python src/server.py
```

You'll see `shopify-mcp starting: MOCK MODE (no live store)`. Every tool call returns realistic sample data — enough to demo the pattern to a stakeholder without touching a real store.

## Quickstart — live Shopify data

Create a Shopify Admin API access token (Settings → Apps → Develop apps → create app → grant scopes). Then:

```bash
export SHOPIFY_STORE_URL="your-store.myshopify.com"
export SHOPIFY_ADMIN_TOKEN="shpat_..."
python src/server.py
```

The server prints `LIVE (your-store.myshopify.com)` and hits the real Admin API on every tool call. Read-only scopes are enough for the six tools included.

### Connect it to Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "shopify": {
      "command": "python",
      "args": ["/absolute/path/to/shopify-mcp/src/server.py"],
      "env": {
        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
        "SHOPIFY_ADMIN_TOKEN": "shpat_..."
      }
    }
  }
}
```

Restart Claude Desktop. Ask *"What's our chargeback rate over the last 30 days?"* — watch Claude call `chargeback_rate`, then call `get_disputes` on its own to explain the drivers.

---

## Example session (mock mode)

```
You:     What's our chargeback rate this month, and what's driving it?

Claude:  Chargeback rate over the last 30 days: 1.21% (5 disputes / 412 orders).
         That flags as "watch" — above the 0.9% comfort zone but not yet in the
         1.5%+ range where payment processors intervene.

         Driver breakdown from get_disputes:
           • 2 chargebacks marked fraudulent ($399.99 combined)
           • 1 chargeback for product_not_received ($245.00)
           • 1 chargeback for credit_not_processed ($199.99)
           • 1 chargeback for duplicate ($67.25)

         Two of the five are still needs_response — evidence deadlines are
         2026-07-20 and 2026-08-14. Want me to pull dispute_details on those
         so you can prep evidence?
```

That's the whole pattern: the model chains its own tool calls, grounds every claim in live data, and asks a useful follow-up.

---

## Why this pattern matters

MCP is the emerging standard for giving AI models **safe, scoped access** to real systems — CRMs, ecommerce platforms, databases, internal APIs. This repo is a minimal, honest reference implementation for the Shopify layer: read-only, no hidden magic, one file to audit.

The same shape scales to production: add tools for `create_evidence`, `issue_refund`, `update_order` when you're ready to grant write access; wrap them in whatever approval flow your ops team requires. The pattern doesn't change — just what the tools do.

---

## Built by

I build AI-agent and automation systems — Claude Code / MCP integrations, LLM-into-workflow tooling, and scripts that kill repetitive work for ecommerce operators. If you need a custom MCP wired into your Shopify (or Stripe, or CRM, or database), that's the work I do.

- **Upwork:** [its_weli on Upwork](https://www.upwork.com/freelancers/~01a1549cfb0817766f)
- **Contact:** [hello@weli.build](mailto:hello@weli.build)
- **Site:** [weli.build](https://weli.build)

---

## License

MIT — use it, fork it, ship it.