Shopify MCP Manager

An MCP (Model Context Protocol) server for fully managing a Shopify store through AI assistants like Cursor or Claude Desktop.

Architecture

┌─────────────────┐     stdio      ┌──────────────────┐    GraphQL    ┌──────────────┐
│  Cursor / Claude │◄──────────────►│  MCP Server      │◄────────────►│  Shopify API │
│  (MCP Client)    │                │  (Node.js)       │              │  Admin API   │
└─────────────────┘                └──────────────────┘              └──────────────┘
                                           │
                                           ▼
                                   ┌──────────────────┐
                                   │  token-store.json │
                                   │  (Access Token)   │
                                   └──────────────────┘

OAuth Flow

┌──────────┐    1. /auth/start     ┌──────────────────┐
│  Browser  │◄────────────────────►│  OAuth Server     │
│           │                      │  (localhost:3847) │
└─────┬─────┘                      └──────────────────┘
      │                                    ▲
      │ 2. Redirect to Shopify             │ 5. Save token
      ▼                                    │
┌──────────────┐  3. Authorize  ┌──────────────────────────────┐
│  Shopify     │───────────────►│  Cloudflare Worker           │
│  Grant Screen│  4. Callback   │  (your-oauth-callback.       │
└──────────────┘  + Auth Code   │   workers.dev)               │
                                │         │                    │
                                │  Redirect to localhost:3847  │
                                │  /callback                   │
                                └──────────────────────────────┘

Prerequisites

• Node.js >= 18
• A Shopify App (created in the Dev Dashboard)
• A Cloudflare Worker for URL redirect (OAuth callback)

Quick Start

1. Install dependencies

npm install

2. Configuration

Copy .env.example to .env and fill in your values:

cp .env.example .env

Required values from the Shopify Dev Dashboard:

• SHOPIFY_API_KEY → Client ID of your app
• SHOPIFY_API_SECRET → Client Secret of your app
• SHOPIFY_DOMAIN → Your myshopify.com domain
• SHOPIFY_REDIRECT_URL → Your Cloudflare Worker callback URL

3. Configure Shopify App

In the Shopify Dev Dashboard under your app:

1. Set App URL to your Cloudflare Worker domain (e.g. https://your-oauth-callback.workers.dev)
2. Add Allowed redirection URLs:

• https://your-oauth-callback.workers.dev/callback

4. Configure Cloudflare Worker

Your Cloudflare Worker must redirect OAuth callbacks from Shopify to your local server.

Example Worker:

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    // OAuth callback from Shopify → Redirect to local server
    if (url.pathname === "/callback") {
      const localUrl = `http://localhost:3847/callback${url.search}`;
      return Response.redirect(localUrl, 302);
    }

    // App URL request from Shopify → Redirect to local server
    if (url.searchParams.has("shop")) {
      const localUrl = `http://localhost:3847${url.pathname}${url.search}`;
      return Response.redirect(localUrl, 302);
    }

    return new Response("Shopify OAuth Endpoint active.", { status: 200 });
  },
};

5. Run OAuth

npm run oauth

This starts a local server and opens the browser. Log in to Shopify and grant the permissions. The access token is automatically saved to token-store.json.

6. Configure MCP Server in Cursor

Add the following to your Cursor configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "shopify-manager": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/src/mcp-server.js"],
      "env": {
        "SHOPIFY_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_API_VERSION": "2026-01"
      }
    }
  }
}

Available Tools (30+)

Shop Management

Products

Orders

Customers

Inventory

Discounts

Analytics

OAuth Flow Details

The OAuth 2.0 Authorization Code Grant flow works as follows:

1. Initiation: User starts the OAuth flow via http://localhost:3847/auth/start
2. Redirect to Shopify: The app redirects the user to Shopify's authorization page with:

• client_id (App API Key)
• scope (requested permissions)
• redirect_uri (Cloudflare Worker URL)
• state (nonce for CSRF protection)

1. User authorizes: The store owner grants the requested permissions
2. Callback: Shopify sends an authorization code to the redirect_uri
3. Cloudflare Worker: Redirects the callback to the local OAuth server
4. Security checks:

• HMAC verification (message authenticity from Shopify)
• State/nonce comparison (CSRF protection)
• Shop domain validation

1. Token exchange: The authorization code is exchanged for an access token via POST https://{shop}/admin/oauth/access_token
2. Persistence: The token is saved to token-store.json

Security Notes

• Never commit token-store.json or .env (both are in .gitignore)
• The SHOPIFY_API_SECRET is confidential
• Access tokens have the permissions of the configured scopes
• If you suspect token compromise: rotate the token via the Shopify Dev Dashboard

License

MIT