@anton.andrusenko/shopify-mcp-admin

🛍️ MCP Server for Shopify Admin API — Enable AI agents to manage Shopify stores with 79 powerful tools

✨ Features

• 🛠️ 79 MCP Tools — Complete store management: products, inventory, collections, pages, blogs, redirects, metafields, markets, locales & translations
• 📦 Modular Architecture — 7 modules with optional lazy loading for optimal AI performance (see Tool Modules)
• 🤖 AI-Optimized — Tool descriptions and error messages designed for LLM comprehension
• 🔌 Dual Transport — STDIO for Claude Desktop, HTTP for ChatGPT/OpenAI
• ⚡ Rate Limiting — Automatic retry with exponential backoff for Shopify API limits
• 🔒 Secure — Tokens never exposed to AI agents; validated environment configuration

🚀 Quick Start

Prerequisites

1. Node.js 20+ — Download
2. Shopify Custom App — Create one in your Shopify Admin:
   • Go to Settings → Apps and sales channels → Develop apps
   • Create a new app and configure Admin API scopes (see Required Scopes)
   • Install the app and copy the Admin API access token

Installation

# Run directly with npx (recommended)
npx @anton.andrusenko/shopify-mcp-admin

# Or install globally
npm install -g @anton.andrusenko/shopify-mcp-admin

Setup Wizard (Recommended)

The easiest way to get started is with the interactive setup wizard:

npx @anton.andrusenko/shopify-mcp-admin init

The wizard will:

1. Prompt for your store URL and validate the format
2. Choose authentication method — Legacy token or OAuth 2.0
3. Test the connection — Verifies credentials before saving
4. Select your AI client — Claude Desktop, Cursor, Windsurf, VS Code, LibreChat, or OpenAI
5. Configure tool loading — All tools, role preset, or lazy loading
6. Generate and save config — Creates the appropriate config file for your client

Manual Configuration

Alternatively, set environment variables directly:

export SHOPIFY_STORE_URL=your-store.myshopify.com
export SHOPIFY_ACCESS_TOKEN=shpat_xxxxx

First Tool Invocation

Once connected to an AI agent, try:

"List all products in my Shopify store"

The AI will use the list-products tool to fetch your catalog.

🔐 Authentication Methods

shopify-mcp-admin supports two authentication methods:

Option 1: Legacy Custom App Token (Recommended for existing apps)

If you have a Custom App with a static access token:

SHOPIFY_STORE_URL=mystore.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxx

Option 2: Dev Dashboard (OAuth 2.0)

If you're using Shopify's new Dev Dashboard with client credentials:

SHOPIFY_STORE_URL=mystore.myshopify.com
SHOPIFY_CLIENT_ID=xxxxx
SHOPIFY_CLIENT_SECRET=xxxxx

Tokens are automatically refreshed every 24 hours.

Which Should I Use?

| Scenario | Method | |----------|--------| | Existing Custom App with static token | Legacy (Option 1) | | New Dev Dashboard app | Client Credentials (Option 2) | | Development/Partner store | Either works | | Production store (after Jan 2026) | Client Credentials required |

⚙️ Configuration Reference

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SERVER_MODE | No | local | Server mode: local (single-tenant) or remote (multi-tenant) | | SHOPIFY_STORE_URL | ✅ (local mode) | — | Your Shopify store domain (e.g., your-store.myshopify.com) | | SHOPIFY_ACCESS_TOKEN | ⚡ See below | — | Admin API access token from your Custom App | | SHOPIFY_CLIENT_ID | ⚡ See below | — | Client ID from Dev Dashboard app | | SHOPIFY_CLIENT_SECRET | ⚡ See below | — | Client Secret from Dev Dashboard app | | DATABASE_URL | ✅ (remote mode) | — | PostgreSQL connection URL for multi-tenant mode | | ENCRYPTION_KEY | ✅ (remote mode) | — | 64-char hex key for credential encryption | | SHOPIFY_API_VERSION | No | 2025-10 | Shopify API version | | TRANSPORT | No | stdio | Transport mode: stdio or http | | PORT | No | 3000 | HTTP server port (when TRANSPORT=http) | | DEBUG | No | — | Enable debug logging (1 or true) | | LOG_LEVEL | No | info | Log level: debug, info, warn, error | | SHOPIFY_MCP_LAZY_LOADING | No | false | Enable modular lazy loading (set to true for on-demand module loading) | | SHOPIFY_MCP_ROLE | No | — | Role preset for automatic module loading (see Role Presets) | | ALLOWED_HOSTS | ✅ (remote mode) | — | Comma-separated list of allowed hostnames (e.g., shopify-mcp.com,api.shopify-mcp.com) | | ALLOWED_ORIGINS | ✅ (remote mode) | — | Comma-separated list of allowed CORS origins (e.g., https://shopify-mcp.com) | | METRICS_ENDPOINT_ENABLED | No | false | Enable Prometheus metrics endpoint at /metrics | | ENABLE_HSTS | No | false | Enable HTTP Strict Transport Security headers | | SHUTDOWN_DRAIN_SECONDS | No | 30 | Graceful shutdown drain timeout in seconds (1-300) | | LOG_FORMAT | No | json | Log format: json (production) or pretty (development) | | SENTRY_DSN | No | — | Sentry error tracking DSN (recommended for production) |

Server Modes

shopify-mcp-admin supports two operating modes:

| Mode | Description | Use Case | |------|-------------|----------| | local (default) | Single-tenant with env credentials | Claude Desktop, local AI agents, development | | remote | Multi-tenant with database storage | SaaS platform, hosted service |

Local Mode (default):

• Credentials via SHOPIFY_STORE_URL + SHOPIFY_ACCESS_TOKEN (or OAuth)
• All 79 tools operate on a single store
• No database required
• Works with STDIO and HTTP transports

Remote Mode:

• Multi-tenant with per-tenant credentials stored in PostgreSQL
• Requires DATABASE_URL and ENCRYPTION_KEY
• HTTP transport only (STDIO not supported for multi-tenant)
• Web dashboard available at /app

⚡ Authentication (local mode): Provide EITHER SHOPIFY_ACCESS_TOKEN (legacy) OR both SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET (Dev Dashboard).

Required Shopify Scopes

Configure these scopes when creating your Custom App:

| Scope | Purpose | |-------|---------| | read_products, write_products | Product management | | read_inventory, write_inventory | Inventory management | | read_content, write_content | Pages, blogs, articles | | read_online_store_navigation, write_online_store_navigation | URL redirects | | read_markets, write_markets | Markets (international selling) | | read_locales, write_locales | Shop locales and translations | | read_translations, write_translations | Translatable content |

📖 Setup Guide: Shopify Custom App Documentation

🖥️ Claude Desktop Integration

Step 1: Configure Claude Desktop

Edit your Claude Desktop configuration file:

• macOS: ~/.config/claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 2: Add the MCP Server

Option 1: Legacy Token Authentication

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["-y", "@anton.andrusenko/shopify-mcp-admin"],
      "env": {
        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx"
      }
    }
  }
}

Option 2: Dev Dashboard (OAuth 2.0)

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["-y", "@anton.andrusenko/shopify-mcp-admin"],
      "env": {
        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "xxxxx",
        "SHOPIFY_CLIENT_SECRET": "xxxxx"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Quit and reopen Claude Desktop. You should see "shopify" in the MCP servers list.

Common Issues

| Issue | Solution | |-------|----------| | Server not appearing | Check JSON syntax; ensure no trailing commas | | "Command not found" | Ensure Node.js 20+ is installed and in PATH | | Authentication errors | Verify SHOPIFY_ACCESS_TOKEN is correct |

💬 LibreChat Integration

LibreChat is an open-source AI chat interface that supports MCP servers natively. This section provides a complete guide to set up LibreChat with the Shopify MCP server.

Prerequisites

• Docker Desktop — Download and ensure it's running
• Git — For cloning repositories
• LLM API Key — OpenAI or Anthropic API key for the chat functionality

Quick Setup (Recommended)

Use the included setup script for automated installation:

# Clone this repo (if you haven't already)
git clone https://github.com/AntonAndrusenko/shopify-mcp-admin.git
cd shopify-mcp-admin

# Run the setup script
./scripts/setup-librechat.sh

The script will:

1. Check Docker is installed and running
2. Clone LibreChat to ~/LibreChat
3. Prompt for your Shopify credentials (store URL, access token or OAuth)
4. Create librechat.yaml with MCP server configuration
5. Create docker-compose.override.yml to mount the config
6. Pull Docker images and start all containers
7. Verify the Shopify MCP server loads successfully

Script Options:

# Install to a custom directory
./scripts/setup-librechat.sh --install-dir /path/to/librechat

# Use local development build instead of npm package
./scripts/setup-librechat.sh --use-local

# Show help
./scripts/setup-librechat.sh --help

Manual Setup

Step 1: Clone and Configure LibreChat

# Clone LibreChat
git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat

# Create environment file
cp .env.example .env

Step 2: Create MCP Server Configuration

Create librechat.yaml in the LibreChat directory:

version: 1.2.1

mcpServers:
  shopify:
    type: stdio
    command: npx
    args:
      - -y
      - "@anton.andrusenko/shopify-mcp-admin"
    env:
      SHOPIFY_STORE_URL: "your-store.myshopify.com"
      # Option 1: Access Token
      SHOPIFY_ACCESS_TOKEN: "shpat_xxxxx"
      # Option 2: OAuth (comment out ACCESS_TOKEN, uncomment these)
      # SHOPIFY_CLIENT_ID: "your_client_id"
      # SHOPIFY_CLIENT_SECRET: "your_client_secret"
      LOG_LEVEL: "info"
    serverInstructions: true
    timeout: 30000
    initTimeout: 15000

Step 3: Mount Configuration in Docker

Create docker-compose.override.yml:

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

Step 4: Start LibreChat

# Pull the latest images
docker compose pull

# Start all services
docker compose up -d

# Verify containers are running
docker compose ps

Step 5: Verify MCP Server Loaded

# Check logs for MCP initialization
docker compose logs api | grep -i "mcp"

# You should see:
# [MCP][shopify] Initialized in: XXXXms
# MCP servers initialized successfully. Added 79 MCP tools.

After Installation: Enable MCP in LibreChat

Once LibreChat is running, follow these steps to use the Shopify MCP server:

1. Create an Account

• Open http://localhost:3080 in your browser
• Click "Sign up" and create an account
• Log in with your new credentials

2. Add an LLM API Key

• Click your profile avatar (bottom-left)
• Select Settings
• Go to User Provider Keys
• Add your API key:
  • OpenAI: Paste your sk-... key
  • Anthropic: Paste your sk-ant-... key
• Click Save

3. Select the Shopify MCP Server

• Start a New Chat
• Look for the MCP Servers dropdown in the chat input area (shows a plug icon)
• Click it and select "shopify"
• You should see a "shopify" badge appear, indicating the MCP server is active

4. Test the Integration

Try these prompts to verify everything works:

"What's my store name and what plan am I on?"
"List my products"
"Show me products with low inventory"

Troubleshooting

| Issue | Solution | |-------|----------| | MCP server not appearing | Check logs: docker compose logs api \| grep -i mcp | | "shopify" badge not visible | Refresh the page, or restart: docker compose restart | | Tools not working | Verify Shopify credentials in librechat.yaml | | Docker won't start | Ensure Docker Desktop is running | | Permission denied on script | Run: chmod +x ./scripts/setup-librechat.sh |

Useful Commands

# View LibreChat logs
cd ~/LibreChat && docker compose logs api -f

# View only MCP-related logs
cd ~/LibreChat && docker compose logs api | grep -i "mcp\|shopify"

# Restart LibreChat (after config changes)
cd ~/LibreChat && docker compose restart

# Stop LibreChat
cd ~/LibreChat && docker compose down

# Update LibreChat
cd ~/LibreChat && git pull && docker compose pull && docker compose up -d

📄 Advanced Configuration: See librechat.yaml.example for multi-store setups, role presets, and HTTP/SSE transport modes.

Production Deployment (Admin-Only Access)

LibreChat can be deployed alongside your production MCP server with admin-only access. The deployment is integrated into the main workflow:

1. Configure LibreChat in your .env.deploy file:

   [email protected],[email protected]
   LIBRECHAT_DOMAIN=chat.shopify-mcp.com

2. Deploy with the main script — LibreChat is automatically configured:

   ./DEPLOY-NOW.sh

The integrated deployment will:

• ✅ Configure admin-only access (email whitelist)
• ✅ Set up MCP server connection with your production API key
• ✅ Configure AI model endpoints (OpenAI, Anthropic, Google, Groq)
• ✅ Users provide their own LLM API keys in the UI

📖 Full Guide: See LibreChat Production Deployment
📖 Model Setup: See LibreChat Models Setup

Testing with Remote Production Server

To connect LibreChat to your remote production MCP server (instead of running locally):

1. Get API Key: Visit your production dashboard (e.g., https://shopify-mcp.com/app) → Settings → API Keys
2. Configure LibreChat: Update librechat.yaml with production server URL:

mcpServers:
  shopify-mcp-production:
    type: streamable-http
    url: https://shopify-mcp.com/mcp
    headers:
      Authorization: "Bearer sk_live_YOUR_API_KEY_HERE"
    timeout: 60000
    serverInstructions: true

3. Restart LibreChat: docker compose restart api

📖 Full Guide: See LibreChat Production Testing Guide for detailed instructions, troubleshooting, and security best practices.

🌐 OpenAI/ChatGPT Integration

For OpenAI function calling or ChatGPT plugins, use HTTP transport mode.

Step 1: Start the Server

TRANSPORT=http \
PORT=3000 \
SHOPIFY_STORE_URL=your-store.myshopify.com \
SHOPIFY_ACCESS_TOKEN=shpat_xxxxx \
npx @anton.andrusenko/shopify-mcp-admin

Step 2: Test the Connection

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Step 3: Call a Tool

# Example: List products
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list-products",
      "arguments": { "first": 10 }
    },
    "id": 2
  }'

OpenAI Function Calling Format

Each tool can be converted to OpenAI function format:

{
  "name": "list-products",
  "description": "List products from the Shopify store with optional filtering",
  "parameters": {
    "type": "object",
    "properties": {
      "first": { "type": "number", "description": "Number of products to return" },
      "query": { "type": "string", "description": "Search query" }
    }
  }
}

🎭 Role Presets

Role presets automatically load appropriate tool modules at startup, optimizing the tool set for specific workflows and reducing AI context overhead.

Available Presets

| Preset | Modules | Tools | Use Case | |--------|---------|-------|----------| | inventory-manager | core | 15 | Stock management and inventory operations | | product-manager | core, store-context, collections, product-extensions | 41 | Full product catalog management | | content-manager | core, content | 37 | Pages, blogs, and content marketing | | seo-specialist | core, collections, product-extensions, advanced-redirects | 38 | SEO optimization and URL management | | international-manager | core, store-context, international, collections | 46 | Multi-market and translation management | | full-access | All 7 modules | 81 | Full store administration (includes meta-tools) |

Using Role Presets

Set the SHOPIFY_MCP_ROLE environment variable:

export SHOPIFY_MCP_ROLE=product-manager
npx @anton.andrusenko/shopify-mcp-admin

Or in Claude Desktop config:

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["-y", "@anton.andrusenko/shopify-mcp-admin"],
      "env": {
        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx",
        "SHOPIFY_MCP_ROLE": "product-manager"
      }
    }
  }
}

Module Discovery (Lazy Loading Mode)

When lazy loading is enabled (SHOPIFY_MCP_LAZY_LOADING=true) and no role is set, the server starts with core tools only (15 tools). AI agents can discover and load additional modules dynamically:

1. Discover modules: Use list-modules to see available modules
2. Load modules: Use load-module with the module name to enable tools
3. Suggestions: Tool responses include suggestions for relevant modules to load

Note: When lazy loading is disabled (default), all 79 tools are available immediately and module discovery is not needed.

🛠️ Available Tools

@anton.andrusenko/shopify-mcp-admin provides 79 domain tools organized into 16 categories (plus 2 meta-tools when lazy loading is enabled):

| Tool | Description | |------|-------------| | get-store-info | Get basic store information (name, domain, plan, currency, timezone, email) | | get-store-limits | Get store resource limits (max variants, max options, location limit) | | get-store-features | Get feature flags (gift cards, reports, storefront, bundles, subscriptions) | | get-store-currencies | Get multi-currency configuration (base currency, presentment currencies, formats) | | get-store-shipping | Get shipping configuration (ships-to countries, countries in shipping zones) | | get-store-domain | Get primary domain configuration (hostname, URL, SSL status) | | get-store-taxes | Get tax configuration (taxes included in prices, tax shipping) | | get-store-policies | Get legal policies (privacy, terms of service, refund policy) | | get-store-alerts | Get admin alerts and setup requirements |

Example: Get Store Limits

{
  "maxProductVariants": 2000,
  "maxProductOptions": 3,
  "locationLimit": 1000,
  "redirectLimitReached": false
}

Example: Get Store Features

{
  "giftCards": true,
  "reports": true,
  "storefront": true,
  "bundles": {
    "eligibleForBundles": true
  },
  "sellsSubscriptions": false
}

Example: Get Store Currencies

{
  "currencyCode": "USD",
  "enabledPresentmentCurrencies": ["USD", "EUR", "GBP", "CAD"],
  "currencyFormats": {
    "moneyFormat": "${{amount}}",
    "moneyWithCurrencyFormat": "${{amount}} USD"
  }
}

| Tool | Description | |------|-------------| | create-product | Create a new product with title, description, variants, and images | | get-product | Retrieve a product by ID with full details | | update-product | Update product title, description, status, SEO fields | | delete-product | Delete a product by ID | | list-products | List products with pagination and search | | update-product-variant | Update variant price, SKU, inventory policy | | add-product-image | Add an image to a product from URL |

| Tool | Description | |------|-------------| | get-product-metafields | Get all metafields for a product | | set-product-metafields | Set or update metafields on a product | | delete-product-metafields | Delete specific metafields from a product |

| Tool | Description | |------|-------------| | get-page-metafields | Get all metafields for a page | | set-page-metafields | Set or update metafields on a page | | delete-page-metafields | Delete specific metafields from a page |

| Tool | Description | |------|-------------| | get-blog-metafields | Get all metafields for a blog | | set-blog-metafields | Set or update metafields on a blog | | delete-blog-metafields | Delete specific metafields from a blog | | get-article-metafields | Get all metafields for an article | | set-article-metafields | Set or update metafields on an article | | delete-article-metafields | Delete specific metafields from an article |

| Tool | Description | |------|-------------| | get-collection-metafields | Get all metafields for a collection | | set-collection-metafields | Set or update metafields on a collection | | delete-collection-metafields | Delete specific metafields from a collection |

| Tool | Description | |------|-------------| | create-collection | Create a manual or smart collection | | get-collection | Retrieve collection details and products | | update-collection | Update collection title, description, SEO | | delete-collection | Delete a collection by ID | | list-collections | List all collections with pagination | | add-products-to-collection | Add products to a manual collection | | remove-products-from-collection | Remove products from a manual collection |

| Tool | Description | |------|-------------| | update-product-image | Update image alt text for SEO | | delete-product-image | Delete an image from a product | | reorder-product-images | Reorder product images by position |

| Tool | Description | |------|-------------| | create-redirect | Create a URL redirect (301/302) | | delete-redirect | Delete a URL redirect | | list-redirects | List all URL redirects | | bulk-delete-redirects | Delete multiple redirects by ID | | bulk-delete-redirects-by-search | Delete redirects matching a search query | | import-redirects | Import redirects from CSV URL | | submit-redirect-import | Submit a redirect import job for processing |

| Tool | Description | |------|-------------| | create-page | Create a new page (About, Contact, etc.) | | get-page | Retrieve a page by ID or handle | | update-page | Update page title, content, SEO | | delete-page | Delete a page by ID | | list-pages | List all pages with pagination |

| Tool | Description | |------|-------------| | create-blog | Create a new blog | | update-blog | Update blog title and settings | | delete-blog | Delete a blog (and all articles) | | list-blogs | List all blogs | | create-article | Create a blog article | | update-article | Update article title, content, SEO | | delete-article | Delete an article | | list-articles | List articles in a blog |

| Tool | Description | |------|-------------| | get-inventory | Get inventory levels for a product variant | | update-inventory | Set or adjust inventory quantity | | list-low-inventory | Find products with low stock | | get-bulk-inventory | Get inventory for multiple variants/locations |

| Tool | Description | |------|-------------| | create-market | Create a new market for international selling | | get-market | Retrieve market details and configuration | | update-market | Update market name, currency, or enabled status | | delete-market | Delete a market by ID | | list-markets | List all markets with pagination |

| Tool | Description | |------|-------------| | create-web-presence | Create a web presence linking a market to domains/locales | | update-web-presence | Update web presence default locale or domain settings | | delete-web-presence | Delete a web presence by ID | | list-web-presences | List all web presences with market associations |

| Tool | Description | |------|-------------| | enable-shop-locale | Enable a locale for your shop | | disable-shop-locale | Disable and unpublish a shop locale | | list-shop-locales | List all enabled shop locales |

| Tool | Description | |------|-------------| | register-translations | Register translations for products, collections, etc. | | remove-translations | Remove translations for specific resources |

📦 Tool Modules

shopify-mcp-admin uses a modular architecture to optimize AI agent performance. Instead of loading all 79 tools at startup (which can degrade AI performance by up to 85%), tools can be organized into 7 modules that load on demand when lazy loading is enabled.

How Module Loading Works (when SHOPIFY_MCP_LAZY_LOADING=true)

1. At startup: Only the Core Module (15 tools including meta-tools) is loaded
2. Discovery: AI agents use list-modules to see available modules
3. Loading: AI agents use load-module to enable additional tools

Default behavior: When lazy loading is disabled (default), all 79 domain tools are available immediately without module loading.

4. Suggestions: Tool responses include hints about which modules to load next

Module Dependency Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         CORE MODULE                              │
│        (Always Loaded - 13 domain + 2 meta* tools)              │
│   Products (7) • Inventory (4) • Store Info (2) • Meta* (2)     │
└─────────────────────────────────────────────────────────────────┘
*Meta tools only available when lazy loading is enabled
        │
        ├──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          ▼
┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐
│  STORE CONTEXT    │  │   COLLECTIONS     │  │     CONTENT       │
│     (7 tools)     │  │    (10 tools)     │  │    (22 tools)     │
│   No deps         │  │   No deps         │  │    No deps        │
└───────────────────┘  └───────────────────┘  └───────────────────┘
                               │
        ├──────────────────────┼──────────────────────────────────┐
        │                      │                                  │
        ▼                      ▼                                  ▼
┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐
│   INTERNATIONAL   │  │ PRODUCT EXTENSIONS│  │ ADVANCED REDIRECTS│
│    (14 tools)     │  │     (9 tools)     │  │     (4 tools)     │
│    No deps        │  │    No deps        │  │ Deps: product-ext │
└───────────────────┘  └───────────────────┘  └───────────────────┘

Module: Core (13-15 tools) — Always Loaded

Description: Essential product and inventory management tools that form the foundation for most Shopify operations. Always loaded at startup.

Dependencies: None

Tools:

| Category | Tools | |----------|-------| | Products (7) | create-product, get-product, update-product, delete-product, list-products, update-product-variant, add-product-image | | Inventory (4) | get-inventory, update-inventory, list-low-inventory, get-bulk-inventory | | Store Info (2) | get-store-info, get-store-limits | | Meta Tools (2)* | list-modules, load-module |

*Meta tools are only included when lazy loading is enabled (SHOPIFY_MCP_LAZY_LOADING=true). When disabled (default), core has 13 domain tools.

Use Case: Basic product catalog management, inventory tracking, and store information queries.

Module: Store Context (7 tools)

Description: Extended store configuration and context tools from Epic 11. Provides deep insights into store configuration including features, currencies, shipping, and more.

Dependencies: None

Tools:

• get-store-features — Feature flags (gift cards, reports, storefront, bundles)
• get-store-currencies — Multi-currency configuration
• get-store-shipping — Shipping countries and zones
• get-store-domain — Primary domain configuration
• get-store-taxes — Tax configuration
• get-store-policies — Legal policies (privacy, terms, refund)
• get-store-alerts — Admin alerts and setup requirements

Use Case: Understanding store capabilities before operations, multi-currency setup, tax configuration.

Load Command: load-module(module: "store-context")

Module: Collections (10 tools)

Description: Product collection management for organizing products and navigation. Includes CRUD operations and metafields.

Dependencies: None

Tools:

| Category | Tools | |----------|-------| | CRUD (7) | list-collections, get-collection, create-collection, update-collection, delete-collection, add-products-to-collection, remove-products-from-collection | | Metafields (3) | get-collection-metafields, set-collection-metafields, delete-collection-metafields |

Use Case: Organizing products into collections, SEO optimization, storefront navigation.

Load Command: load-module(module: "collections")

Module: Product Extensions (9 tools)

Description: Extended product management including metafields, advanced image operations, and URL redirects for SEO.

Dependencies: None

Tools:

| Category | Tools | |----------|-------| | Metafields (3) | get-product-metafields, set-product-metafields, delete-product-metafields | | Images (3) | update-product-image, delete-product-image, reorder-product-images | | Redirects (3) | create-redirect, list-redirects, delete-redirect |

Use Case: Adding custom metadata to products, SEO image alt text, URL redirects when changing product handles.

Load Command: load-module(module: "product-extensions")

Module: Content (22 tools)

Description: Content management for pages, blogs, and articles. Complete CRUD operations plus metafields for content marketing and SEO.

Dependencies: None

Tools:

| Category | Tools | |----------|-------| | Pages (8) | list-pages, get-page, create-page, update-page, delete-page, get-page-metafields, set-page-metafields, delete-page-metafields | | Blogs (7) | list-blogs, create-blog, update-blog, delete-blog, get-blog-metafields, set-blog-metafields, delete-blog-metafields | | Articles (7) | list-articles, create-article, update-article, delete-article, get-article-metafields, set-article-metafields, delete-article-metafields |

Use Case: Content marketing, blog management, static pages (About, Contact, FAQ).

Load Command: load-module(module: "content")

Module: International (14 tools)

Description: International commerce and localization tools. Markets, web presence, and shop locale translations for multi-region stores.

Dependencies: None

Tools:

| Category | Tools | |----------|-------| | Markets (5) | list-markets, get-market, create-market, update-market, delete-market | | Web Presence (4) | list-web-presences, create-web-presence, update-web-presence, delete-web-presence | | Translations (5) | list-shop-locales, enable-shop-locale, disable-shop-locale, register-translations, remove-translations |

Use Case: Multi-region selling, localized storefronts, translation management.

Load Command: load-module(module: "international")

Module: Advanced Redirects (4 tools)

Description: Bulk URL redirect operations for large-scale SEO management. Import and mass-delete capabilities.

Dependencies: product-extensions (auto-loaded when you load this module)

Tools:

• bulk-delete-redirects — Delete multiple redirects by ID
• bulk-delete-redirects-by-search — Delete redirects matching a search query
• import-redirects — Import redirects from CSV URL
• submit-redirect-import — Submit a redirect import job for processing

Use Case: Site migrations, bulk URL updates, SEO cleanup operations.

Load Command: load-module(module: "advanced-redirects")

Note: Loading this module automatically loads product-extensions (9 tools) as a dependency.

Choosing the Right Module

| If you need to... | Load these modules | |-------------------|-------------------| | Manage basic products and inventory | Core only (default) | | Work with collections and organize products | collections | | Add product metafields or manage images | product-extensions | | Manage blog posts and pages | content | | Set up international markets | international | | Bulk manage URL redirects | advanced-redirects | | Full store administration | Use full-access role preset |

🔄 Upgrading from Previous Versions

What's New in v2.0.0+: Modular Tool Loading

Starting with v2.0.0, shopify-mcp-admin supports modular lazy loading to optimize AI agent performance. Research shows that presenting more than 30 tools to an AI agent can degrade performance by up to 85%.

Default Behavior (All Tools Loaded):

• All 79 domain tools are loaded at startup for maximum compatibility
• Works with Claude Desktop and all MCP clients
• Server instructions describe all tools as immediately available
• Module meta-tools (list-modules, load-module) are NOT registered (not needed)

Optional: Enable Lazy Loading:

• Only 15 core tools are loaded at startup (13 domain + 2 meta-tools)
• Additional tools are loaded on-demand via load-module
• AI agents discover available modules using list-modules
• Token usage reduced by up to 81% compared to loading all tools
• Server instructions explain module discovery and loading

Note: Claude Desktop doesn't support dynamic tool list refresh, so lazy loading is disabled by default. Enable it for MCP clients that support notifications/tools/list_changed.

Enabling Lazy Loading

For MCP clients that support dynamic tool refresh:

# Option 1: Environment variable
export SHOPIFY_MCP_LAZY_LOADING=true

# Option 2: In MCP client config
{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["-y", "@anton.andrusenko/shopify-mcp-admin"],
      "env": {
        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx",
        "SHOPIFY_MCP_LAZY_LOADING": "true"
      }
    }
  }
}

Configuration Options

1. Default (all tools) — All 79 domain tools available immediately. Best for Claude Desktop and MCP clients without dynamic tool refresh.

2. Role Preset — Pre-configured module sets for specific workflows:

   export SHOPIFY_MCP_ROLE=product-manager

3. Lazy Loading — Enable for MCP clients that support notifications/tools/list_changed:

   export SHOPIFY_MCP_LAZY_LOADING=true

   • AI uses list-modules to see available modules
   • AI uses load-module with module name to enable tools
   • Tool responses suggest relevant modules automatically

When to Use Each Mode

| Mode | Tools | Best For | |------|-------|----------| | Default (all tools) | 79 | Claude Desktop, maximum compatibility | | Role Preset | 15-81 based on role | Specific workflows (e.g., content manager) | | Lazy Loading | 15 at startup | MCP clients with dynamic tool refresh |

Performance Comparison

| Mode | Tools at Startup | Est. Token Usage | AI Performance | |------|------------------|------------------|----------------| | Lazy Loading | 15 | ~4,500 | ⭐⭐⭐ Optimal | | inventory-manager | 15 | ~4,500 | ⭐⭐⭐ Optimal | | content-manager | 37 | ~11,100 | ⭐⭐ Good | | product-manager | 41 | ~12,300 | ⭐⭐ Good | | international-manager | 46 | ~13,800 | ⭐⭐ Good | | full-access / Default | 79-81 | ~24,000 | ⭐ May degrade |

Troubleshooting Module Loading

| Issue | Solution | |-------|----------| | Tool not found with lazy loading | Load the appropriate module: load-module(module: "collections") | | "Module not found" error | Use list-modules to see valid module names | | Want modular lazy loading | Set SHOPIFY_MCP_LAZY_LOADING=true (requires MCP client that supports tool list refresh) | | AI agent loading too many modules | Use a role preset instead of on-demand loading |

🔧 Troubleshooting

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | 401 Unauthorized | Invalid access token | Regenerate token in Shopify Admin | | 403 Forbidden | Missing API scopes | Add required scopes to Custom App | | 429 Too Many Requests | Rate limited | Wait; shopify-mcp-admin auto-retries | | ECONNREFUSED | Server not running | Start server with npx @anton.andrusenko/shopify-mcp-admin | | Invalid store URL | Wrong URL format | Use store.myshopify.com format |

Debug Mode

Enable verbose logging to diagnose issues:

# Option 1: DEBUG flag
DEBUG=1 npx @anton.andrusenko/shopify-mcp-admin

# Option 2: LOG_LEVEL
LOG_LEVEL=debug npx @anton.andrusenko/shopify-mcp-admin

MCP Inspector

Use MCP Inspector to visually test and debug the server:

# Test production build
npm run build
npm run inspect

# Development mode (no build needed)
npm run inspect:dev

# With saved configuration
cp mcp-inspector.example.json mcp-inspector.json
# Edit mcp-inspector.json with your credentials
npm run inspect:config

MCP Inspector opens a web UI at http://localhost:6274 where you can:

• 📋 Browse registered tools with schemas (79 tools by default, or 15 core tools with lazy loading)
• 📦 Test module loading via list-modules and load-module (when lazy loading is enabled)
• 📊 Access 9 MCP resources for store context
• ▶️ Execute tools interactively and view results
• 🔍 Inspect JSON-RPC protocol messages
• 📊 Monitor server events in real-time

Tip: Copy mcp-inspector.example.json to mcp-inspector.json for pre-configured role presets like product-manager or full-access.

📊 MCP Resources

The MCP server exposes comprehensive store context information via MCP resources. These are read-only data sources that AI agents can query for context.

Extended Store Resources

| Resource URI | Description | |--------------|-------------| | shopify://store/info | Basic store info (name, domain, plan, currency, timezone) | | shopify://store/limits | Resource limits (max variants, max options, location limit) | | shopify://store/features | Feature flags (gift cards, reports, storefront, bundles) | | shopify://store/currencies | Multi-currency configuration (base currency, presentment currencies) | | shopify://store/shipping | Shipping configuration (ships-to countries, shipping zones) | | shopify://store/domain | Primary domain configuration (hostname, URL, SSL status) | | shopify://store/taxes | Tax configuration (taxes included, tax shipping) | | shopify://store/policies | Legal policies (privacy, terms of service, refund) | | shopify://store/alerts | Admin alerts and setup requirements |

Note: For MCP clients that don't support resources (e.g., Claude Desktop), equivalent tools are available. See Store Info Tools below.

FAQ

Q: Can I connect to multiple stores?
A: Run separate server instances with different credentials.

Q: Does this work with development stores?
A: Yes, development stores work with Custom Apps.

Q: How do I test without affecting production?
A: Use a development store for testing.

Q: Where can I report bugs?
A: Open an issue on GitHub Issues.

🔄 CI/CD Pipeline

This project uses GitHub Actions for continuous integration and automated releases.

Continuous Integration

Every push to main and every pull request triggers the CI workflow:

# Runs on Node.js 20.x and 22.x
npm ci        # Install dependencies
npm run lint  # Biome linting
npm run typecheck  # TypeScript type checking
npm run test  # Vitest unit tests
npm run build # Production build

All checks must pass before merging pull requests.

Automated Releases

To publish a new version to npm:

# 1. Update version (creates git tag automatically)
npm version patch  # or minor, or major

# 2. Push commit and tag
git push origin main --follow-tags

The release workflow automatically:

1. Runs all CI checks
2. Publishes to npm with provenance
3. Tags the npm package to match the git tag

Repository Setup (for Maintainers)

Required Secrets

Configure these in Settings → Secrets and variables → Actions:

| Secret | Description | |--------|-------------| | NPM_TOKEN | npm automation token for publishing (create one) |

Branch Protection (Recommended)

Enable these settings for the main branch in Settings → Branches:

• ✅ Require a pull request before merging
• ✅ Require status checks to pass before merging
  • Select: build (20.x) and build (22.x)
• ✅ Require branches to be up to date before merging

🎨 Tenant Dashboard (Remote Mode)

When running in remote mode (SERVER_MODE=remote), shopify-mcp-admin includes a web-based dashboard for tenant management. The dashboard provides a modern, responsive UI for:

• Shop Management — View and connect Shopify stores
• API Key Management — Generate, copy, and revoke API keys
• Usage Statistics — Monitor API calls and activity
• Account Settings — Update profile and change password

Accessing the Dashboard

1. Start the server in remote mode:

SERVER_MODE=remote npm start

2. Navigate to http://localhost:3000/app in your browser

3. Log in with your tenant credentials

Dashboard Features

• ✨ Modern UI — Built with React, Vite, and Tailwind CSS
• 📱 Responsive Design — Works on desktop, tablet, and mobile
• ♿ Accessible — WCAG AA compliant with keyboard navigation
• 🔐 Secure — Session-based authentication with HttpOnly cookies
• 🎯 Optimized — <150KB gzipped bundle size

Tech Stack

• Frontend: React 18 + Vite + TypeScript
• Styling: Tailwind CSS + shadcn/ui components
• State: React Query for server state management
• Forms: React Hook Form + Zod validation
• Auth: Session cookies with automatic expiry handling

🤝 Contributing

Contributions are welcome! Here's how to get started:

Development Setup

# Clone the repository
git clone https://github.com/AntonAndrusenko/shopify-mcp-admin.git
cd shopify-mcp-admin

# Install dependencies
npm install

# Run in development mode
npm run dev

Available Scripts

| Command | Description | |---------|-------------| | npm run dev | Start development server with hot reload | | npm run build | Build for production | | npm run test | Run unit tests | | npm run test:coverage | Run tests with coverage report | | npm run lint | Run Biome linter | | npm run lint:fix | Auto-fix linting issues | | npm run inspect | Open MCP Inspector with production build | | npm run inspect:dev | Open MCP Inspector in development mode |

Pull Request Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run npm run lint && npm run test
5. Commit with conventional commits (feat:, fix:, docs:, etc.)
6. Open a Pull Request

Code Style

This project uses Biome for linting and formatting. Configuration is in biome.json.

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol by Anthropic
• Shopify Admin API
• Built with TypeScript, Express, and Zod

🚀 Deployment

shopify-mcp-admin supports multiple deployment options for different environments.

Production Deployment

For production deployment on Railway with Cloudflare, Sentry, and uptime monitoring, see the comprehensive deployment guide:

📖 Production Deployment Guide

The guide includes:

• Railway Setup: Step-by-step instructions for deploying to Railway
• Cloudflare DNS: DNS configuration and SSL/TLS setup
• Database Setup: Prisma migrations and backup strategy
• Staging Environment: Separate staging deployment configuration
• Monitoring: Sentry error tracking and uptime monitoring setup
• LibreChat Integration: Automatically deployed with admin-only access (optional)

Quick Deploy: Run ./DEPLOY-NOW.sh - LibreChat is included automatically if configured in .env.deploy

Production URLs

The production service is available at:

Root Domain:

• Dashboard: https://shopify-mcp.com/ → redirects to /app
• Dashboard UI: https://shopify-mcp.com/app
• Health Check: https://shopify-mcp.com/health
• Metrics: https://shopify-mcp.com/metrics
• MCP Endpoint: https://shopify-mcp.com/mcp

API Subdomain:

• Dashboard: https://api.shopify-mcp.com/app
• Health Check: https://api.shopify-mcp.com/health
• Metrics: https://api.shopify-mcp.com/metrics
• MCP Endpoint: https://api.shopify-mcp.com/mcp

Available Endpoints:

| Endpoint | Description | Authentication | |----------|-------------|----------------| | / | Root path - redirects to /app (dashboard) | None | | /app | Dashboard UI (React SPA) | Session cookie | | /health | Health check endpoint | None | | /metrics | Prometheus metrics | None | | /mcp | MCP protocol endpoint | API key or session | | /api/tenants | Tenant management API | Session cookie | | /api/shops | Shop connection API | Session cookie | | /api/keys | API key management | Session cookie |

Note: The root domain (shopify-mcp.com) redirects to the dashboard (/app) for a better user experience. All API endpoints are also available on the root domain.

Deployment Options

Railway (Recommended for Quick Start)

Deploy to Railway with the included railway.json configuration:

1. Connect your GitHub repository to Railway
2. Add environment variables (DATABASE_URL, ENCRYPTION_KEY, etc.)
3. Deploy — Railway auto-detects the Dockerfile

Kubernetes

For self-hosted or cloud Kubernetes clusters, see the Kubernetes Deployment Guide.

Quick start:

# Build and push image
docker build -t yourregistry/shopify-mcp-admin:v2.0.0 .
docker push yourregistry/shopify-mcp-admin:v2.0.0

# Configure and deploy
cd k8s
kustomize edit set image shopify-mcp-admin=yourregistry/shopify-mcp-admin:v2.0.0
kubectl apply -k .

Docker (Local/Development)

# Build image
docker build -t shopify-mcp-admin .

# Run container
docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://..." \
  -e ENCRYPTION_KEY="..." \
  shopify-mcp-admin

Image Size: The production Docker image is optimized for minimal size (<150MB) with multi-stage Alpine Linux build.

Environment Variables

For production environment variables, see:

📄 .env.production.example

This template includes all required and optional environment variables with descriptions, example values, and generation instructions.

Quick Start: Local vs Production

| Mode | Use Case | Transport | Database | Credentials | |------|----------|-----------|----------|-------------| | Local | Development, Claude Desktop | STDIO or HTTP | None | Environment variables | | Remote | Production, SaaS platform | HTTP only | PostgreSQL | Database (encrypted) |

Local Mode (default):

export SHOPIFY_STORE_URL=your-store.myshopify.com
export SHOPIFY_ACCESS_TOKEN=shpat_xxxxx
npx @anton.andrusenko/shopify-mcp-admin

Remote Mode (production):

export SERVER_MODE=remote
export DATABASE_URL=postgresql://...
export ENCRYPTION_KEY=<64-char-hex>
export TRANSPORT=http
# See .env.production.example for all variables