Shopify Catalog MCP

An MCP server that lets AI agents search products across all Shopify merchants via the Shopify Global Catalog API.

Why?

Shopify's Catalog API requires a UCP agent profile to be embedded in every request. Claude Code's built-in HTTP MCP client can't inject this metadata, so direct connection fails.

This MCP server acts as a local proxy — it wraps your requests in the proper JSON-RPC format, injects the agent profile, and forwards them to Shopify.

Tools

Tool	Description
search_catalog	Search products across all Shopify merchants by text query, with optional filters (price, shipping country)
get_product	Get full details for a single product including variants, options, and checkout URLs
lookup_catalog	Look up specific products or variants by their IDs (up to 50 at once)

Setup

1. Host a UCP Agent Profile

Create a JSON file and host it at any public HTTPS URL (GitHub Pages, Vercel, Netlify, etc.):

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{ "version": "2026-04-08" }],
      "dev.ucp.shopping.catalog.lookup": [{ "version": "2026-04-08" }],
      "dev.shopify.catalog.global": [{ "version": "2026-04-08" }]
    }
  }
}

A copy is included in this repo as ucp-agent-profile.json.

2. Add to Claude Code

Option A: Global (available in all projects)

claude mcp add -s user shopify-catalog \
  -e UCP_AGENT_PROFILE_URL=https://your-domain.com/ucp-agent-profile.json \
  -- npx shopify-catalog-mcp

Option B: Project-level (in .mcp.json)

{
  "mcpServers": {
    "shopify-catalog": {
      "command": "npx",
      "args": ["shopify-catalog-mcp"],
      "env": {
        "UCP_AGENT_PROFILE_URL": "https://your-domain.com/ucp-agent-profile.json"
      }
    }
  }
}

3. Restart Claude Code

The MCP server will be available after restarting your session.

How It Works

Claude Code → this MCP server (local stdio) → Shopify Catalog API
                       ↑
                injects UCP agent profile
                into every JSON-RPC request

Each tool call is forwarded to https://catalog.shopify.com/api/ucp/mcp with the proper format:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": { "ucp-agent": { "profile": "https://your-domain.com/profile.json" } },
      "catalog": { "query": "running shoes", "filters": { "available": true } }
    }
  }
}

What You Get Back

Products include structured data: title, description, price range, images, options, variants with availability, checkout URLs, seller info, and ratings.

The checkout_url on each variant goes straight to the store's checkout with the item in cart — no need to browse the store.

No API Keys Required

The Shopify Catalog API doesn't require OAuth or API keys. The only requirement is the UCP agent profile hosted at a public URL. No secrets to manage.

License

MIT