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