README.md
The most complete open-source MCP server and CLI for Shopify.
cob-shopify-mcp
The most complete open-source MCP server and CLI for Shopify. 59 built-in tools + 5 custom tools across 5 domains — use it as an MCP server for AI agents (Claude, Cursor, Windsurf) or as a standalone CLI to manage Shopify stores directly from your terminal.
Features
- 59 built-in tools + 5 custom tools across 5 domains — Products (15), Orders (17), Customers (9), Inventory (7), Analytics (16)
- Standalone CLI — natural domain commands from the terminal without MCP (
cob-shopify products list --limit 5,orders get --id ..., etc.) - MCP server — connect to Claude, Cursor, Windsurf, or any MCP-compatible AI agent
- 4 MCP resources (Shop info, Locations, Policies, Currencies)
- 4 MCP prompts (Health check, Sales report, Inventory risk, Support summary)
- Dual transport — stdio (default) + Streamable HTTP
- 3 auth methods — Static token, OAuth client credentials, OAuth authorization code
- Cost tracking — Every response includes Shopify API cost metadata
- Rate limiting — Respects Shopify's cost-based throttling
- Query caching — Configurable TTL per query type
- 82% less context bloat — Advertise-and-Activate mode: 1 meta-tool instead of 59 schemas, domains loaded on demand
- Config-driven — YAML config, env vars, CLI overrides
- Type-safe — Full TypeScript with Zod validation
Why cob-shopify-mcp
| What you get | |
|---|---|
| Dual-mode | Same 64 tools work as both CLI commands and MCP server — no competitor offers both |
| ShopifyQL Analytics | 16 analytics tools powered by ShopifyQL — sales summaries, cohort analysis, vendor performance, period-over-period comparison — each in a single API call |
| 82% less AI context | Advertise-and-Activate loads 1 meta-tool instead of 59 schemas. Domains activate on demand |
| Production-grade | Cost-based rate limiting, query caching, retry with backoff, encrypted token storage, 600 tests |
MCP vs CLI — When to Use What
This project gives you two ways to interact with Shopify. Same tools, same engine, same auth — different interfaces.
| CLI | MCP | |
|---|---|---|
| What it is | Direct terminal commands | Protocol for AI agents |
| Who it's for | Developers, scripts, CI/CD | Claude, Cursor, Windsurf, custom agents |
| How to use | cob-shopify products list --limit 5 |
AI calls tools via MCP protocol |
| Install via | npm install -g cob-shopify-mcp |
Same npm install, then claude mcp add |
| Docker | Not applicable | Yes — HTTP transport for remote/multi-agent |
| Custom YAML tools | Auto-discovered | Auto-discovered |
| Output | Table (TTY), JSON when piped; --json, --fields, --jq |
JSON via MCP response |
| Schema introspection | --schema flag on any command |
Built into MCP protocol |
| Context window | Zero impact — no tool schemas loaded | All schemas injected — use Advertise-and-Activate for 82% reduction |
| Best for | Quick lookups, scripting, pipelines, CI/CD | Conversational AI, multi-step workflows |
You don't have to choose — install once, use both:
# CLI — run directly from terminal
cob-shopify products list --limit 5
cob-shopify products list --limit 5 --fields id,title,status
cob-shopify orders get --id gid://shopify/Order/123 --json
# MCP — connect to Claude and let AI use the same tools
claude mcp add cob-shopify-mcp -- cob-shopify-mcp start
Advertise-and-Activate
Every MCP server on GitHub dumps all tool schemas into the AI's context on connect. With 59 tools, that's ~19,000 tokens consumed before the user even asks a question. Most conversations use 1-2 tools — 95% of those tokens are wasted.
Advertise-and-Activate fixes this. Instead of loading all 59 tool schemas, the server registers a single activate_tools meta-tool with a lightweight domain summary:
Before (default): 59 tool schemas → ~19,000 tokens per prompt
After (activate): 1 meta-tool → ~300 tokens per prompt
On-demand: AI activates 1 domain → +2,000-3,000 tokens only when needed
How it works:
- Connect — AI sees 1 tool:
activate_toolswith a description listing all domains and their tool counts - Activate —
Tools (1)
activate_toolsMeta-tool to load specific Shopify domain toolsets on demand to reduce context bloat.Environment Variables
SHOPIFY_STORE_URLrequiredThe URL of your Shopify store (e.g., your-store.myshopify.com)SHOPIFY_ACCESS_TOKENrequiredAdmin API access token for your Shopify storeConfiguration
claude_desktop_config.json
{"mcpServers": {"cob-shopify-mcp": {"command": "npx", "args": ["-y", "cob-shopify-mcp", "start"], "env": {"SHOPIFY_STORE_URL": "your-store.myshopify.com", "SHOPIFY_ACCESS_TOKEN": "your-access-token"}}}}Try it
→List the 5 most recently added products in my Shopify store.
→Generate a sales report for the last 30 days comparing performance to the previous period.
→Check current inventory levels for products with low stock and suggest reorder quantities.
→Summarize the latest customer orders and identify any high-value customers.
→Get details for the order with ID gid://shopify/Order/123456789.