@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 multiple authentication methods depending on your use case:

Authentication Methods Overview

| Method | Use Case | Client Types | |--------|----------|--------------| | OAuth 2.0 Authorization Code + PKCE | Web-based AI clients with browser | ChatGPT MCP Apps, Claude Web Custom Connectors | | API Key Bearer Token | Desktop/CLI apps, programmatic access | Claude Desktop, Cursor, LibreChat, VS Code | | Legacy Custom App Token | Local development, single-tenant | STDIO transport, local testing | | Dev Dashboard Client Credentials | Shopify Dev Dashboard apps | Local development with OAuth |

Which Method Should I Use?

| Your Client | Recommended Method | |-------------|-------------------| | ChatGPT (MCP Apps) | OAuth 2.0 (automatic via DCR) — See ChatGPT Integration | | Claude Web (Custom Connectors) | OAuth 2.0 (automatic via DCR) — See Claude Web Integration | | Claude Desktop | API Key Bearer Token — See Claude Desktop | | Cursor, VS Code | API Key Bearer Token — See LibreChat | | LibreChat | API Key Bearer Token — See LibreChat | | Local Development | Legacy Token or Dev Dashboard |

Option 1: OAuth 2.0 Authorization Code + PKCE (ChatGPT, Claude Web)

For web-based AI clients that support OAuth 2.0:

• Automatic client registration via Dynamic Client Registration (RFC 7591)
• PKCE required with S256 method (RFC 7636)
• No manual credentials needed — clients handle registration automatically
• Browser-based authorization with consent page

The server exposes discovery endpoints at:

• /.well-known/oauth-authorization-server (RFC 8414)
• /.well-known/oauth-protected-resource (RFC 9728)

See OAuth 2.0 Endpoints Reference for details.

Option 2: API Key Bearer Token (Claude Desktop, Cursor, LibreChat)

For desktop apps and programmatic access:

1. Get API Key: Visit your MCP Dashboard (/app) → Settings → API Keys
2. Generate Key: Click "Create New Key" and copy the sk_live_... key
3. Configure Client: Add Authorization: Bearer sk_live_... header
4. Ensure a Default Shop is set: In the dashboard, go to Settings → Default Shop (recommended, especially if you have multiple shops connected)

# Example: Test with curl
curl -X POST https://shopify-mcp.com/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Cursor note: Cursor does not run an OAuth “Connect” flow inside MCP. Use an API key + streamable-http transport, and connect your Shopify store via the dashboard (/app) first.

Option 3: Legacy Custom App Token (Local Development)

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

SHOPIFY_STORE_URL=mystore.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxx

Option 4: Dev Dashboard Client Credentials (Local Development)

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.

Remote mode note (multi-tenant): Shops connected via OAuth now support expiring offline tokens with automatic refresh (Shopify Dec 2025 refresh tokens). See docs/TOKEN-REFRESH-IMPLEMENTATION.md.

⚙️ 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) | | 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.

🤖 ChatGPT MCP Apps Integration

ChatGPT supports connecting to MCP servers via OAuth 2.0 Authorization Code Flow with PKCE. This is the recommended method for ChatGPT Plus/Pro/Team/Enterprise users.

How It Works

When you add the Shopify MCP server in ChatGPT:

1. ChatGPT discovers the OAuth endpoints via /.well-known/oauth-authorization-server (RFC 8414)
2. ChatGPT registers itself as an OAuth client via /oauth/register (RFC 7591 Dynamic Client Registration)
3. You authorize the connection via a consent page at /oauth/authorize
4. ChatGPT exchanges the authorization code for tokens via /oauth/token
5. ChatGPT uses the access token to call MCP tools

No manual client_id or client_secret needed — ChatGPT handles registration automatically!

Prerequisites

1. Deployed MCP Server — Your server running in remote mode at https://shopify-mcp.com (or your own domain)
2. Shopify Store Connected — At least one shop connected in your MCP Dashboard
3. ChatGPT Plus/Pro/Team/Enterprise — MCP Apps require a paid ChatGPT subscription

Step-by-Step Setup

Step 1: Ensure Your Shop is Connected

1. Visit your MCP Dashboard: https://shopify-mcp.com/app
2. Log in or register a tenant account
3. Go to Shops and connect your Shopify store (OAuth or manual token)
4. Verify the shop shows as "Connected"

Step 2: Add MCP Server in ChatGPT

1. Open ChatGPT → Settings → Connectors (or Apps)
2. Enable Developer Mode in Advanced Settings (if required)
3. Click Create or Add New MCP Server
4. Fill in the configuration:

| Field | Value | |-------|-------| | Name | Shopify MCP | | Description | Manage Shopify store: products, inventory, collections, content, SEO | | MCP Server URL | https://shopify-mcp.com/mcp | | Authentication | OAuth 2.0 (auto-detected via discovery) |

5. Click Save or Connect

Step 3: Authorize the Connection

1. ChatGPT will open an authorization page at https://shopify-mcp.com/oauth/authorize
2. Log in with your MCP Dashboard credentials (same email/password)
3. Review the requested scopes and click Authorize
4. You'll be redirected back to ChatGPT with the connection established

Step 4: Test the Connection

In ChatGPT, try:

"List all products in my Shopify store"

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

ChatGPT Troubleshooting

| Issue | Solution | |-------|----------| | "OAuth discovery failed" | Verify server is running: curl https://shopify-mcp.com/.well-known/oauth-authorization-server | | "Client registration failed" | Check server logs for registration errors | | "Authorization failed" | Ensure you're logged in to the MCP Dashboard with the correct account | | "No shop configured" | Connect a shop in your MCP Dashboard first | | "Token expired" | Re-authorize the connection in ChatGPT settings | | Connection timeout | Check server health: curl https://shopify-mcp.com/health |

Re-Authorization

If your connection stops working:

1. Go to ChatGPT → Settings → Connectors
2. Find the Shopify MCP connection and click Disconnect
3. Click Connect again to start a fresh OAuth flow
4. Complete the authorization as described above

🔮 Claude Web Custom Connectors Integration

Claude Web (claude.ai) supports MCP connections via Custom Connectors using the same OAuth 2.0 Authorization Code Flow with PKCE.

Plan Requirements: Claude Web Custom Connectors require Claude Pro, Max, Team, or Enterprise subscription.

How It Works

Claude Web's Custom Connectors work similarly to ChatGPT's MCP Apps:

1. Claude discovers OAuth endpoints via /.well-known/oauth-authorization-server
2. Claude registers as an OAuth client via Dynamic Client Registration (RFC 7591)
3. You authorize the connection via the consent page
4. Claude exchanges the authorization code for tokens
5. Claude uses the access token for MCP tool calls

Prerequisites

1. Deployed MCP Server — Your server at https://shopify-mcp.com (or your own domain)
2. Shopify Store Connected — At least one shop connected in your MCP Dashboard
3. Claude Pro/Max/Team/Enterprise — Custom Connectors require a paid subscription

Step-by-Step Setup

Step 1: Ensure Your Shop is Connected

1. Visit your MCP Dashboard: https://shopify-mcp.com/app
2. Log in or register a tenant account
3. Connect your Shopify store under Shops

Step 2: Add Custom Connector in Claude Web

1. Go to claude.ai → Settings (gear icon)
2. Navigate to Integrations or Custom Connectors
3. Click Add Connector or New
4. Fill in the configuration:

| Field | Value | |-------|-------| | Name | Shopify MCP | | Description | Manage Shopify store via MCP | | Server URL | https://shopify-mcp.com/mcp |

5. Click Save or Connect

Step 3: Authorize the Connection

1. Claude will redirect you to https://shopify-mcp.com/oauth/authorize
2. Log in with your MCP Dashboard credentials
3. Review and approve the authorization request
4. You'll be redirected back to Claude with the connection active

Step 4: Test the Connection

In Claude, try:

"What products are in my Shopify store?"

Claude will use the MCP tools to query your store.

Claude Web Troubleshooting

| Issue | Solution | |-------|----------| | "Custom Connectors not available" | Upgrade to Claude Pro, Max, Team, or Enterprise | | "OAuth flow failed" | Verify server discovery: curl https://shopify-mcp.com/.well-known/oauth-authorization-server | | "Authorization error" | Ensure you're using the correct MCP Dashboard credentials | | "Connector not responding" | Check server health: curl https://shopify-mcp.com/health | | "Token expired" | Disconnect and reconnect the Custom Connector |

Re-Authorization

If the connection expires or breaks:

1. Go to Claude Web → Settings → Integrations
2. Find the Shopify connector and click Remove or Disconnect
3. Add the connector again and complete the authorization flow

🔌 OAuth 2.0 Endpoints Reference

The MCP server exposes the following OAuth 2.0 endpoints for client authentication:

| Endpoint | Method | Description | RFC | |----------|--------|-------------|-----| | /.well-known/oauth-authorization-server | GET | Authorization server metadata (issuer, endpoints, capabilities) | RFC 8414 | | /.well-known/oauth-protected-resource | GET | Protected resource metadata (resource server, scopes) | RFC 9728 | | /oauth/register | POST | Dynamic Client Registration (automatic client registration) | RFC 7591 | | /oauth/authorize | GET | Authorization endpoint with consent UI | RFC 6749 | | /oauth/token | POST | Token endpoint (authorization_code, refresh_token grants) | RFC 6749, RFC 7636 |

OAuth Flow Diagram

┌─────────────┐                                    ┌─────────────────────────┐
│   ChatGPT   │                                    │    MCP Server           │
│  or Claude  │                                    │  (shopify-mcp.com)      │
└──────┬──────┘                                    └───────────┬─────────────┘
       │                                                       │
       │  1. GET /.well-known/oauth-authorization-server       │
       │ ───────────────────────────────────────────────────>  │
       │  <─── Authorization server metadata (RFC 8414)        │
       │                                                       │
       │  2. POST /oauth/register (Dynamic Client Registration)│
       │ ───────────────────────────────────────────────────>  │
       │  <─── client_id, client_secret (RFC 7591)             │
       │                                                       │
       │  3. Redirect user to /oauth/authorize?client_id=...   │
       │     &redirect_uri=...&code_challenge=...&state=...    │
       │ ───────────────────────────────────────────────────>  │
       │                                                       │
       │        ┌─────────────────────────────────────────┐    │
       │        │ User sees consent page, logs in,        │    │
       │        │ approves authorization                   │    │
       │        └─────────────────────────────────────────┘    │
       │                                                       │
       │  <─── Redirect to callback with authorization code    │
       │                                                       │
       │  4. POST /oauth/token (exchange code for tokens)      │
       │     code=...&code_verifier=...&grant_type=...         │
       │ ───────────────────────────────────────────────────>  │
       │  <─── access_token, refresh_token (RFC 6749/7636)     │
       │                                                       │
       │  5. POST /mcp (with Bearer access_token)              │
       │ ───────────────────────────────────────────────────>  │
       │  <─── MCP tool results                                │
       └───────────────────────────────────────────────────────┘

Discovery Endpoint Example

curl https://shopify-mcp.com/.well-known/oauth-authorization-server

{
  "issuer": "https://shopify-mcp.com",
  "authorization_endpoint": "https://shopify-mcp.com/oauth/authorize",
  "token_endpoint": "https://shopify-mcp.com/oauth/token",
  "registration_endpoint": "https://shopify-mcp.com/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_post"]
}

🌐 OpenAI/ChatGPT Integration (Alternative Methods)

In addition to the OAuth-based ChatGPT MCP Apps integration above, you can also use API key authentication for programmatic access.

Option 1: Local Server (Development)

Run the server locally for development and testing with OpenAI function calling.

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
  }'

Option 3: Remote Server with Bearer Token

Connect to your production MCP server from any OpenAI-compatible client.

# Authenticated request to remote server
curl -X POST https://your-server.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

OpenAI Function Calling Format

Each tool can be converted to OpenAI function format for custom integrations:

{
  "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 |

OAuth Connection Troubleshooting

If you're having issues connecting ChatGPT or Claude Web via OAuth:

"OAuth discovery failed" or "Server not found"

1. Verify the server is running:

   curl https://shopify-mcp.com/.well-known/oauth-authorization-server

   Expected: JSON response with issuer, authorization_endpoint, etc.

2. Check server health:

   curl https://shopify-mcp.com/health

   Expected: 200 OK with {"status": "healthy", ...}

"Client registration failed"

• Cause: Dynamic Client Registration (DCR) endpoint issue
• Solution: Check server logs for /oauth/register errors
• Verify: curl -X POST https://shopify-mcp.com/oauth/register -H "Content-Type: application/json" -d '{"client_name":"test","redirect_uris":["https://example.com/callback"]}'

"Authorization failed" or "Invalid credentials"

• Cause: Wrong MCP Dashboard credentials
• Solution: Log in to https://shopify-mcp.com/app directly to verify your email/password
• Note: OAuth login uses your MCP Dashboard account, not Shopify credentials

"No shop configured" or "No shops connected"

• Cause: No Shopify store connected to your tenant account
• Solution:
  1. Log in to https://shopify-mcp.com/app
  2. Go to Shops → Connect Shop
  3. Complete the OAuth flow or enter a manual access token

"Token expired" or "Access denied"

• Cause: OAuth access token expired (tokens last 1 hour by default)
• Solution:
  1. Disconnect the MCP connection in ChatGPT/Claude settings
  2. Reconnect and complete the OAuth flow again
  3. The server will issue fresh tokens

"PKCE verification failed"

• Cause: PKCE code_verifier doesn't match code_challenge
• Solution: This is a client-side issue; report to ChatGPT/Claude support
• Note: The server requires S256 PKCE method (plain is not supported)

"Invalid redirect_uri"

• Cause: The OAuth callback URL doesn't match a registered pattern
• Solution:
  • ChatGPT: Redirect URIs must match https://chatgpt.com/* or https://chat.openai.com/*
  • Claude Web: Redirect URIs must match https://claude.ai/*

Re-Authorizing OAuth Connections

If your OAuth connection stops working:

For ChatGPT:

1. Go to ChatGPT → Settings → Connectors (or Apps)
2. Find the Shopify MCP connection
3. Click Disconnect or Remove
4. Click Connect again and complete the OAuth flow

For Claude Web:

1. Go to claude.ai → Settings → Integrations
2. Find the Shopify MCP connector
3. Click Disconnect or Remove
4. Re-add the connector and authorize again

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. Bump version (does NOT create a tag)
npm run version:patch  # or version:minor, or version:major

# 2. Commit + push the version bump to main (this triggers CI + Railway auto-deploy)
git add package.json package-lock.json
git commit -m "Release v$(node -p \"require('./package.json').version\")"
git push origin main

# 3. Create and push the version tag (this triggers the Release workflow)
VERSION=$(node -p "require('./package.json').version")
git tag "v$VERSION"
git push origin "v$VERSION"

The release workflow automatically:

1. Reads release notes from CHANGELOG.md
2. Builds the package (including dashboard assets)
3. Publishes to npm
4. Creates a GitHub Release

Important: The Release workflow triggers on tags (v*) and does not rerun the full CI matrix. Tag releases only after the CI workflow is green for the commit you’re tagging.

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

Shopify Token Refresh (Remote Mode)

When shops are connected via OAuth in remote mode, the server stores expiring offline tokens (access + refresh token) and refreshes access tokens automatically before they expire.

• Legacy compatibility: Existing non-expiring tokens continue to work; shops upgrade to refreshable tokens on reconnect.
• DB migration required: Ensure Prisma migrations are deployed in production before rolling out the server.
• Details: See docs/TOKEN-REFRESH-IMPLEMENTATION.md.

🤝 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

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 expe