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.
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.
git clone https://github.com/weli-dev/shopify-mcp
cd shopify-mcp
pip install -r requirements.txt
python src/server.pyYou'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.
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.pyThe 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.
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.
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.
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.
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
MIT — use it, fork it, ship it.