# Cob Shopify Mcp

> Production-grade MCP server and CLI tool for Shopify Admin GraphQL API — 49+ tools, YAML-extensible, dual auth, dual transport, Docker-ready

- **Type:** MCP server
- **Install:** `agentstack add mcp-callobuzz-cob-shopify-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [callobuzz](https://agentstack.voostack.com/s/callobuzz)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [callobuzz](https://github.com/callobuzz)
- **Source:** https://github.com/callobuzz/cob-shopify-mcp
- **Website:** https://callobuzz.com/open-source

## Install

```sh
agentstack add mcp-callobuzz-cob-shopify-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
# 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:**

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

Or via environment variable:

```bash
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:

```bash
# 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:

```bash
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

```mermaid
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.

```bash
npm install -g cob-shopify-mcp
```

**Connect to Claude CLI:**

```bash
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:

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

**Or with npx (no install at all):**

```bash
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)):

```json
{
  "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:**

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

**B2. Connect to Claude CLI:**

```bash
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:

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

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

```json
{
  "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:**

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

Edit `.env` with your credentials:

```env
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:**

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

Verify it's running:

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

**C3. Connect to Claude CLI:**

```bash
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)):

```json
{
  "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](https://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](https://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

5. Scroll down to the **Access** section
6. 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`:
> ```
> read_products, read_orders, read_all_orders, read_draft_orders, read_customers, read_inventory, read_locations, read_fulfillments, read_assigned_fulfillment_orders, read_me

…

## 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](https://github.com/callobuzz)
- **Source:** [callobuzz/cob-shopify-mcp](https://github.com/callobuzz/cob-shopify-mcp)
- **License:** MIT
- **Homepage:** https://callobuzz.com/open-source

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-callobuzz-cob-shopify-mcp
- Seller: https://agentstack.voostack.com/s/callobuzz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.