Cob Shopify Mcp

cob-shopify-mcp

[](https://www.npmjs.com/package/cob-shopify-mcp) [](https://github.com/svinpeace/cob-shopify-mcp/actions) [](./LICENSE) [](https://nodejs.org/) [](https://github.com/svinpeace/cob-shopify-mcp#tools-reference) [](https://www.typescriptlang.org/) [](https://github.com/callobuzz/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](#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:

1. Connect — AI sees 1 tool: activate_tools with a description listing all domains and their tool counts
2. Activate — AI calls activate_tools("analytics") — server dynamically registers 16 analytics tools
3. Execute — AI calls top_products as normal

Typical conversation: ~2,800 tokens instead of ~19,000. That's an 82% reduction.

No competitor Shopify MCP server has this. It requires clean domain grouping, a dynamic registry, and a meta-tool pattern — all built into this server's architecture.

Enable it:

# cob-shopify-mcp.config.yaml
tools:
  advertise_and_activate: true

Or via environment variable:

COB_SHOPIFY_ADVERTISE_AND_ACTIVATE=true

Custom YAML tools are included automatically — they declare a domain and appear in the corresponding summary.

CLI as Agent Tool (Zero-Config AI Access)

AI agents like Claude Code and Cursor have built-in terminal access. That means they can run CLI commands directly — no MCP server needed, no config required:

# AI agent runs this via its Bash tool — zero setup
cob-shopify products list --limit 5 --json
cob-shopify orders get-by-name --name "#1001" --json
cob-shopify analytics sales-summary --start_date 2026-01-01 --end_date 2026-03-15 --json

Every command outputs clean JSON when piped or when --json is passed. The AI reads the output and uses the data. The --schema flag lets the AI discover what inputs any command accepts:

cob-shopify products list --schema   # AI reads the schema, knows what flags to pass

No MCP connection, no server process, no protocol overhead. Just npm install -g cob-shopify-mcp and the AI can use every tool immediately.

| | CLI via Agent's Terminal | MCP Protocol | |---|---|---| | Setup | npm install -g only | Install + claude mcp add config | | Tool discovery | --schema flag per command | Automatic schema injection | | Context cost | Zero tokens | ~16K tokens (or ~800 with Advertise-and-Activate) | | Best for | Quick access, zero-config, CI/CD | Rich tool discovery, multi-agent, streaming |

You don't have to choose — install once, use both. Same tools, same engine, same Shopify API.

Use Cases

flowchart LR
    subgraph AGENTS["Your AI Layer"]
        direction TB
        SALES["Sales Assistant"]
        SUPPORT["Customer Support Bot"]
        WAREHOUSE["Warehouse Manager"]
        SHIPPING["Shipping Tracker"]
        BI["Business Intelligence"]
        AUTO["Automation Workflows"]
    end

    MCP["cob-shopify-mcp\n59 tools · 4 resources · 4 prompts\nAdvertise-and-Activate: 82% less context"]

    SHOPIFY["Shopify Store"]

    AGENTS --> MCP --> SHOPIFY

| Role | What it does | Tools used | |------|-------------|------------| | Sales Assistant | Answer product questions, check inventory, create draft orders, look up customer history and lifetime value | search_products, get_product, list_inventory_levels, create_draft_order, get_customer_lifetime_value | | Customer Support Bot | Look up orders by name/number, track fulfillment, view timeline, pull customer details | get_order_by_name, get_order_fulfillment_status, get_order_timeline, get_customer, get_customer_orders | | Warehouse Manager | Monitor stock levels, get low-stock alerts, adjust inventory, check location inventory | low_stock_report, list_inventory_levels, adjust_inventory, set_inventory_level, get_location_inventory | | Shipping Executive | Track fulfillment status, view order details, update order notes/tags | get_order_fulfillment_status, list_orders, add_order_note, update_order_tags | | Business Intelligence | Sales summaries, top products, refund rates, repeat customer analysis, inventory risk | sales_summary, top_products, refund_rate_summary, repeat_customer_rate, inventory_risk_report | | Automation Pipeline | Bulk product updates, tag management, order processing, customer segmentation | update_product, manage_product_tags, add_order_tag, add_customer_tag, create_product |

Integration Patterns

1. Direct MCP (simplest) — Claude, Cursor, or any MCP client connects directly:

AI Agent → MCP Protocol → cob-shopify-mcp → Shopify API

2. Agent Orchestration Layer — Your custom agent framework uses MCP as the Shopify bridge:

User → Your App → Agent Layer (LangChain, CrewAI, etc.) → MCP Client → cob-shopify-mcp → Shopify API

3. RAG + MCP — Combine retrieval-augmented generation with live Shopify data:

User → Your App → RAG (product docs, policies, FAQs) + MCP (live store data) → Response

4. Multi-Agent System — Multiple specialized agents share one MCP server:

Sales Agent    ─┐
Support Agent  ─┤→ cob-shopify-mcp (HTTP transport) → Shopify API
Warehouse Agent─┘

Quick Start

> Binary names: cob-shopify for CLI use, cob-shopify-mcp for MCP server setup. Same binary, two names.

> First: Complete [Getting Shopify Credentials](#getting-shopify-credentials) below to get your Client ID, Client Secret, and store domain. Then come back here.

Pick one of the three paths below. All get you to the same result — a working MCP server connected to Claude.

---

Path A: npm install (simplest — no clone, no build)

Install globally and connect in two commands. No .env file needed — credentials go straight into the Claude config.

npm install -g cob-shopify-mcp

Connect to Claude CLI:

claude mcp add cob-shopify-mcp \
  -e SHOPIFY_CLIENT_ID=your_client_id \
  -e SHOPIFY_CLIENT_SECRET=shpss_your_secret \
  -e SHOPIFY_STORE_DOMAIN=your-store.myshopify.com \
  -- cob-shopify-mcp start

Done. Claude launches the server automatically when needed. Verify:

claude mcp list
# cob-shopify-mcp: ... - ✓ Connected

Or with npx (no install at all):

claude mcp add cob-shopify-mcp \
  -e SHOPIFY_CLIENT_ID=your_client_id \
  -e SHOPIFY_CLIENT_SECRET=shpss_your_secret \
  -e SHOPIFY_STORE_DOMAIN=your-store.myshopify.com \
  -- npx cob-shopify-mcp start

Or connect to Claude Desktop — add to claude_desktop_config.json ([file location](#claude-desktop-config-location)):

{
  "mcpServers": {
    "cob-shopify-mcp": {
      "command": "cob-shopify-mcp",
      "args": ["start"],
      "env": {
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "shpss_your_secret",
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

Restart Claude Desktop after saving. You'll see the tools icon showing 59 available tools.

---

Path B: Clone and build (for development / contributing)

Clone the repo and build from source. Claude launches the server via stdio — you don't run it yourself.

B1. Clone and build:

git clone https://github.com/svinpeace/cob-shopify-mcp.git
cd cob-shopify-mcp
pnpm install
pnpm build

B2. Connect to Claude CLI:

claude mcp add cob-shopify-mcp \
  -e SHOPIFY_CLIENT_ID=your_client_id \
  -e SHOPIFY_CLIENT_SECRET=shpss_your_secret \
  -e SHOPIFY_STORE_DOMAIN=your-store.myshopify.com \
  -- node /absolute/path/to/cob-shopify-mcp/dist/cli/index.js start

Done. Verify:

claude mcp list
# cob-shopify-mcp: ... - ✓ Connected

Or connect to Claude Desktop — add to claude_desktop_config.json ([file location](#claude-desktop-config-location)):

{
  "mcpServers": {
    "cob-shopify-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cob-shopify-mcp/dist/cli/index.js", "start"],
      "env": {
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "shpss_your_secret",
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

---

Path C: Docker (long-running HTTP server)

Run the server as a container via HTTP transport. Good for always-on setups, VPS deployments, or shared team access.

C1. Clone and configure:

git clone https://github.com/svinpeace/cob-shopify-mcp.git
cd cob-shopify-mcp
cp .env.example .env

Edit .env with your credentials:

SHOPIFY_CLIENT_ID=your_client_id
SHOPIFY_CLIENT_SECRET=shpss_your_secret
SHOPIFY_STORE_DOMAIN=your-store.myshopify.com

C2. Build and start the container:

docker compose up --build
# Server starts at http://127.0.0.1:3000

Verify it's running:

curl http://127.0.0.1:3000/health
# {"status":"ok"}

C3. Connect to Claude CLI:

claude mcp add --transport http shopify http://127.0.0.1:3000

# Verify
claude mcp list
# cob-shopify-mcp: http://127.0.0.1:3000 (HTTP) - ✓ Connected

Or connect to Claude Desktop — add to claude_desktop_config.json ([file location](#claude-desktop-config-location)):

{
  "mcpServers": {
    "cob-shopify-mcp": {
      "url": "http://127.0.0.1:3000"
    }
  }
}

> Windows note: Use 127.0.0.1 not localhost — Docker on Windows may not bind to IPv6 ::1 which localhost can resolve to.

---

Claude Desktop config file location:

| OS | Path | |----|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

Getting Shopify Credentials

Everything happens through the Shopify Developer Dashboard at dev.shopify.com. You need two things: a dev store (free) and an app with the right scopes.

Step 1 — Sign in to the Developer Dashboard

1. Go to dev.shopify.com
2. Sign in with your Shopify account (or create one — it's free, no credit card needed)
3. You'll land on the Developer Dashboard with Apps, Dev stores, and Catalogs in the left sidebar

Step 2 — Create a development store

You need a store to test against. Dev stores are free and never expire.

1. Click Dev stores in the left sidebar
2. Click Create store
3. Fill in the store name (e.g., my-dev-store) — this becomes my-dev-store.myshopify.com
4. Complete the setup

> Note your store domain — you'll need it: my-dev-store.myshopify.com

Step 3 — Create an app and configure scopes

1. Click Apps in the left sidebar
2. Click Create app (top-right)
3. Enter an app name (e.g., Shopify MCP Server) and click Next
4. You'll land on the version configuration page

1. Scroll down to the Access section
2. Click Select scopes — this opens a dropdown where you can either:

• Search and check each scope individually, or
• Paste a comma-separated list directly into the field

Full access (recommended — copy-paste this entire block):

read_products, write_products, read_orders, write_orders, read_all_orders, read_draft_orders, write_draft_orders, read_order_edits, write_order_edits, read_customers, write_customers, read_inventory, write_inventory, read_locations, read_fulfillments, write_fulfillments, read_assigned_fulfillment_orders, write_assigned_fulfillment_orders, read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders, read_third_party_fulfillment_orders, write_third_party_fulfillment_orders, read_shipping, read_reports, read_legal_policies

> Read-only? Use only the read scopes and set COB_SHOPIFY_READ_ONLY=true in .env: > ``` > readproducts, readorders, readallorders, readdraftorders, readcustomers, readinventory, readlocations, readfulfillments, readassignedfulfillmentorders, readme

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: callobuzz
• Source: callobuzz/cob-shopify-mcp
• License: MIT
• Homepage: https://callobuzz.com/open-source

Install and usage instructions live in the source repository linked above.