Kockatoos Shopify MCP Server

Website | npm | GitHub

An MCP (Model Context Protocol) server that gives AI agents full access to the Shopify Admin API. Manage products, orders, customers, collections, fulfillments, discounts, and more through 136 tools powered by the Shopify Admin GraphQL API.

Installation

npm install @kockatoos/shopify-mcp

Or run directly with npx (no install needed):

npx @kockatoos/shopify-mcp

Quick Start

Step 1 — Create a Shopify app

You need a Shopify app with an access token to authenticate. There are two types:

Option A: Admin-created custom app (simplest)

1. Go to Shopify Admin → Settings → Apps and sales channels → Develop apps
2. Create an app, configure the required Admin API scopes, and click Install app
3. Copy the Admin API access token shown once after installation

Use it directly in your MCP config:

{
  "mcpServers": {
    "kockatoos-shopify-mcp": {
      "command": "npx",
      "args": ["-y", "@kockatoos/shopify-mcp"],
      "env": {
        "SHOPIFY_STORE_NAME": "your-store-name",
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Option B: Partner Dashboard app

Partner Dashboard apps use OAuth and don't expose an access token in the UI. Run the one-time token helper to get a permanent offline access token:

# With npm install
SHOPIFY_CLIENT_ID=xxx SHOPIFY_CLIENT_SECRET=yyy SHOPIFY_STORE_NAME=zzz \
  npx shopify-mcp-get-token

# Or if you cloned the repo
SHOPIFY_CLIENT_ID=xxx SHOPIFY_CLIENT_SECRET=yyy SHOPIFY_STORE_NAME=zzz \
  npm run get-token

Before running: add http://localhost:3456/callback to your app's Allowed Redirect URLs in the Partner Dashboard (App setup → URLs).

This opens a browser, completes the OAuth flow, and prints your access token. Then use it in your MCP config the same way as Option A.

Step 2 — Configure your MCP client

Add this to your MCP client configuration (e.g. claude_desktop_config.json, .vscode/mcp.json, or equivalent):

{
  "mcpServers": {
    "kockatoos-shopify-mcp": {
      "command": "npx",
      "args": ["-y", "@kockatoos/shopify-mcp"],
      "env": {
        "SHOPIFY_STORE_NAME": "your-store-name",
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Using a local clone

git clone https://github.com/untitled-developers/shopify-mcp.git
cd shopify-mcp
npm install
npm run build

Then point your MCP client to the built output:

{
  "mcpServers": {
    "kockatoos-shopify-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/shopify-mcp/dist/index.js"],
      "env": {
        "SHOPIFY_STORE_NAME": "your-store-name",
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Configuration

| Variable | Required | Description | |----------|----------|-------------| | SHOPIFY_STORE_NAME | Yes | Your store subdomain (e.g. my-store, not the full .myshopify.com) | | SHOPIFY_ACCESS_TOKEN | Yes* | Permanent access token (from admin-created app or Partner Dashboard OAuth flow) | | SHOPIFY_API_VERSION | No | API version (defaults to 2026-01) |

* SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET can be used instead of SHOPIFY_ACCESS_TOKEN only for admin-created custom apps (store-only, no Partner Dashboard support).

Available Tools (136)

Shop (1)

| Tool | Description | |------|-------------| | get_shop_info | Get store name, domain, email, plan, currency, timezone |

Products (11)

| Tool | Description | |------|-------------| | list_products | List products with filters (status, vendor, type) and pagination | | get_product | Get full product details including variants and images | | create_product | Create a product with title, description, variants, images | | update_product | Update product fields (title, description, status, tags, etc.) | | delete_product | Permanently delete a product by ID | | list_product_metafields | List all metafields for a product (GraphQL) | | get_product_metafield | Get a product metafield by namespace and key (GraphQL) | | set_product_metafield | Create or update a product metafield via metafieldsSet (GraphQL) | | delete_product_metafield | Delete a product metafield (GraphQL) | | list_metafield_definitions | List all product metafield definitions with validations (GraphQL) | | create_metafield_definition | Create a new metafield definition for products (or other resource types) with validation rules (GraphQL) |

Product Images (5)

| Tool | Description | |------|-------------| | list_product_images | List all images for a product | | get_product_image | Get a specific product image | | create_product_image | Add an image to a product (by URL or base64) | | update_product_image | Update image alt text or position | | delete_product_image | Remove an image from a product |

Variants (5)

| Tool | Description | |------|-------------| | list_variants | List all variants of a product | | get_variant | Get a specific variant | | create_variant | Add a new variant to a product | | update_variant | Update variant price, SKU, inventory, etc. | | delete_variant | Remove a variant from a product |

Collections (13)

| Tool | Description | |------|-------------| | list_custom_collections | List custom (manual) collections | | list_smart_collections | List smart (automated) collections | | get_custom_collection | Get a custom collection by ID | | get_smart_collection | Get a smart collection by ID | | create_custom_collection | Create a manual collection | | create_smart_collection | Create an automated collection with rules | | update_custom_collection | Update a custom collection | | delete_custom_collection | Delete a custom collection | | update_smart_collection | Update a smart collection | | reorder_collection_products | Reorder products in a manual collection | | add_product_to_collection | Add a product to a custom collection | | remove_product_from_collection | Remove a product from a custom collection | | list_collection_products | List all products in a collection |

Orders (9)

| Tool | Description | |------|-------------| | list_orders | List orders with filters (status, financial status, date range) | | get_order | Get full order details (line items, shipping, transactions) | | update_order | Update order notes, tags, or email | | close_order | Mark an order as closed/completed | | cancel_order | Cancel an order with optional reason, email notification, restock | | list_order_metafields | List all metafields for an order (GraphQL) | | get_order_metafield | Get an order metafield by namespace and key (GraphQL) | | set_order_metafield | Create or update an order metafield via metafieldsSet (GraphQL) | | delete_order_metafield | Delete an order metafield (GraphQL) |

Customers (9)

| Tool | Description | |------|-------------| | list_customers | List customers with pagination | | search_customers | Search by email, name, country, etc. | | get_customer | Get full customer details and addresses | | create_customer | Create a customer with email, name, phone, addresses | | update_customer | Update customer fields | | list_customer_metafields | List all metafields for a customer (GraphQL) | | get_customer_metafield | Get a customer metafield by namespace and key (GraphQL) | | set_customer_metafield | Create or update a customer metafield via metafieldsSet (GraphQL) | | delete_customer_metafield | Delete a customer metafield (GraphQL) |

Inventory (5)

| Tool | Description | |------|-------------| | list_locations | List all warehouse/store locations | | get_location | Get details of a specific location | | list_inventory_levels | Get stock quantities at a location | | adjust_inventory | Adjust stock by a relative amount (+/-) | | set_inventory | Set stock to an absolute quantity |

Draft Orders (7)

| Tool | Description | |------|-------------| | list_draft_orders | List draft orders with pagination | | get_draft_order | Get a draft order by ID | | create_draft_order | Create a new draft order with line items | | update_draft_order | Update a draft order | | complete_draft_order | Convert a draft order into a real order | | send_draft_order_invoice | Email the draft order invoice to the customer | | delete_draft_order | Delete a draft order |

Discounts — Compatibility Wrappers / GraphQL (8)

These tools keep the older Price Rules-style MCP names for backward compatibility, but they now call modern Admin GraphQL code-discount operations. Returned IDs and payloads are GraphQL discount node/redeem-code shapes.

| Tool | Description | |------|-------------| | list_price_rules | List code discounts through the compatibility wrapper | | get_price_rule | Get a code discount by DiscountCodeNode ID | | create_price_rule | Create a basic code discount | | update_price_rule | Update a basic code discount | | delete_price_rule | Delete a code discount | | list_discount_codes | List redeem codes for a code discount | | create_discount_code | Set the code on a basic code discount | | delete_discount_code | Delete a redeem code from a code discount |

Discounts — Code Discounts / GraphQL (11)

Modern Shopify GraphQL discount API for code-based discounts (amount off, BXGY, free shipping).

| Tool | Description | |------|-------------| | list_code_discounts | List code discounts (paginated, optional search query) | | get_code_discount | Get a code discount by GID or by code string | | create_code_discount_basic | Create an amount-off code discount | | update_code_discount_basic | Update an amount-off code discount | | create_code_discount_bxgy | Create a Buy X Get Y code discount | | update_code_discount_bxgy | Update a Buy X Get Y code discount | | create_code_discount_free_shipping | Create a free-shipping code discount | | update_code_discount_free_shipping | Update a free-shipping code discount | | activate_code_discount | Activate a code discount | | deactivate_code_discount | Deactivate a code discount | | delete_code_discount | Delete a code discount by GID |

Discounts — Automatic Discounts / GraphQL (11)

Modern Shopify GraphQL discount API for automatic discounts (applied without a code).

| Tool | Description | |------|-------------| | list_automatic_discounts | List automatic discounts (paginated, optional search query) | | get_automatic_discount | Get an automatic discount by GID | | create_automatic_discount_basic | Create an amount-off automatic discount | | update_automatic_discount_basic | Update an amount-off automatic discount | | create_automatic_discount_bxgy | Create a Buy X Get Y automatic discount | | update_automatic_discount_bxgy | Update a Buy X Get Y automatic discount | | create_automatic_discount_free_shipping | Create a free-shipping automatic discount | | update_automatic_discount_free_shipping | Update a free-shipping automatic discount | | activate_automatic_discount | Activate an automatic discount | | deactivate_automatic_discount | Deactivate an automatic discount | | delete_automatic_discount | Delete an automatic discount by GID |

Fulfillments (5)

| Tool | Description | |------|-------------| | list_fulfillment_orders | List fulfillment orders for an order | | list_fulfillments | List fulfillments for an order | | create_fulfillment | Create a fulfillment with tracking info | | update_fulfillment_tracking | Update tracking number/URL on a fulfillment | | cancel_fulfillment | Cancel a fulfillment |

Webhooks (5)

| Tool | Description | |------|-------------| | list_webhooks | List all registered webhooks | | get_webhook | Get a webhook by ID | | create_webhook | Register a new webhook | | update_webhook | Update a webhook URL or topic | | delete_webhook | Remove a webhook |

Menus (5)

| Tool | Description | |------|-------------| | list_menus | List navigation menus | | get_menu | Get a navigation menu by ID | | create_menu | Create a navigation menu | | update_menu | Update a navigation menu | | delete_menu | Delete a navigation menu |

Files (5)

| Tool | Description | |------|-------------| | list_files | List files in Shopify Files | | create_file | Create a file from a staged upload or URL | | update_file | Update file metadata | | delete_files | Delete one or more files | | stage_upload | Create a staged upload target |

Apps (2)

| Tool | Description | |------|-------------| | list_app_installations | List app installations | | get_app_installation | Get an app installation by ID |

Themes (10)

| Tool | Description | |------|-------------| | list_themes | List online store themes | | get_theme | Get a theme by ID | | create_theme | Create a theme from a source URL | | update_theme | Update theme metadata | | publish_theme | Publish a theme | | delete_theme | Delete a theme | | list_theme_files | List files in a theme | | get_theme_files | Read theme file contents | | upsert_theme_files | Create or update theme files | | delete_theme_files | Delete theme files |

Pages (5)

| Tool | Description | |------|-------------| | list_pages | List online store pages | | get_page | Get a page by ID | | create_page | Create a page | | update_page | Update a page | | delete_page | Delete a page |

Bundles (4)

| Tool | Description | |------|-------------| | create_bundle | Create a product bundle operation | | update_bundle | Update a product bundle operation | | get_bundle | Get a bundle product by ID | | get_bundle_operation | Get a bundle operation by ID |

Authentication

The server uses Shopify's client_credentials OAuth grant — no browser-based authorization needed. It automatically obtains and caches an access token on the first API call.

Required app scopes (configure in Shopify Admin → App → API access):

• read_products, write_products
• read_orders, write_orders
• read_customers, write_customers
• read_inventory, write_inventory
• read_locations
• read_draft_orders, write_draft_orders
• read_discounts, write_discounts
• read_shipping, write_shipping
• read_fulfillments, write_fulfillments

Development

# Run directly with ts-node (reads .env automatically)
npm run dev

# Build to dist/
npm run build

# Run compiled version
npm start

Architecture

src/
├── index.ts              # MCP server entry — wires everything together
├── config.ts             # Environment variable loading & validation
├── auth.ts               # Token management (client_credentials grant)
├── shopify-client.ts     # Admin GraphQL HTTP client
└── tools/
    ├── shop.ts           # Store info
    ├── products.ts       # Products, product metafields, metafield definitions
    ├── images.ts         # Product images
    ├── variants.ts       # Product variants
    ├── collections.ts    # Custom & smart collections
    ├── orders.ts         # Orders & order metafields
    ├── customers.ts      # Customers & customer metafields
    ├── inventory.ts      # Locations & inventory levels
    ├── draft-orders.ts   # Draft orders
    ├── discounts.ts      # GraphQL code, automatic, and compatibility discount tools
    ├── fulfillments.ts   # Fulfillments & tracking
    └── webhooks.ts       # Webhook management

License

MIT