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)

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:

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:

{
  "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
• Contact: hello@weli.build
• Site: weli.build

---

License

MIT — use it, fork it, ship it.