Shopify MCP Server

An opinionated Model Context Protocol (MCP) server focused on Shopify product lookup and order status retrieval. It exposes structured MCP tools you can call from AI assistants (Cursor, VS Code MCP extensions, etc.) to search products, fetch full product details, check order status, recommendations, inventory, returns, and more.

File name note: rename this to README.md before publishing to npm so it is picked up automatically.

Core Shopify Tools

| Tool | Purpose | Key Inputs | |------|---------|-----------| | shopify_search_products | Lightweight product search + summary | query (string), optional category, limit | | shopify_get_product_detail | Full product detail by id / handle / exact title (with fuzzy fallback) | One of: id, handle, title | | shopify_get_order_status | Order fulfillment + item + address summary | orderNumber and/or email | | shopify_get_recommendations | Mock AI recommendations (replace with real logic) | userId, optional category, recentPurchases, limit | | shopify_update_preferences | Store (mock) user preference blob | userId, preferences | | shopify_check_inventory | Variant inventory snapshot | productIds (array of numeric ids) | | shopify_process_return | Mock return initiation | orderId, items, reason, returnType |

Response Shapes (Highlights)

shopify_search_products returns array of simplified product objects (id, title, description, price, inStock, variants, images).

shopify_get_product_detail returns normalized rich product object: variants, images, collections, metafields, inventory totals, SEO, etc. Fuzzy similarity score attached when found by approximate title.

shopify_get_order_status returns: orderNumber, status, orderDate, estimatedDelivery (simple +5 day calc), currentLocation (derived), items[], totals, shipping & billing addresses.

Resources

| URI | Description | |-----|-------------| | test://info | Basic server info text | | test://sample-data | Sample JSON payload |

Prerequisites

1. Node.js >= 18
2. A Shopify store + Private App / Custom App access token with relevant scopes (read_products, read_orders, etc.)

Environment Variables

Set these before running (shell example):

export SHOPIFY_SHOP_DOMAIN="your-shop.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="shpat_***"
# Optional (defaults shown):
export SHOPIFY_API_VERSION="2024-01"

Install & Build

npm install
npm run build

Run (Shopify Server Entrypoint)

After compiling, run:

node build/shopify-mcp.js

Or add a script in package.json (recommended):

"scripts": {
  "start:shopify": "node build/shopify-mcp.js"
}

Editor Integration Examples

Cursor (~/.cursor/config.json)

{
  "mcp": {"servers": {"shopify": {"command": "node","args": ["/ABS/PATH/TO/build/shopify-mcp.js"],"env": {"SHOPIFY_SHOP_DOMAIN": "your-shop.myshopify.com","SHOPIFY_ACCESS_TOKEN": "shpat_***"}}}}
}

VS Code (settings.json)

{
  "mcp.servers": {
    "shopify": {
      "command": "node",
      "args": ["/ABS/PATH/TO/build/shopify-mcp.js"],
      "env": {
        "SHOPIFY_SHOP_DOMAIN": "your-shop.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_***"
      }
    }
  }
}

Usage Examples (Natural Language Prompts)

Ask your MCP-enabled AI:

• "Search Shopify for running shoes under $150" (calls shopify_search_products)
• "Get full details for product handle 'ultra-boost-23'" (calls shopify_get_product_detail)
• "What's the status of order 12345 for [email protected]" (calls shopify_get_order_status)
• "Recommend 4 products similar to recent headphones purchase for user U123" (calls shopify_get_recommendations)

Typical Tool Argument Forms

// Product search
{ "query": "wireless headphones", "category": "Audio", "limit": 5 }

// Product detail by id
{ "id": "gid://shopify/Product/1234567890" }

// Product detail by handle
{ "handle": "wireless-headphones-pro" }

// Product detail by title (fuzzy fallback)
{ "title": "Wireless Headphones Pro" }

// Order status
{ "orderNumber": "#12345", "email": "[email protected]" }

// Inventory check
{ "productIds": [1234567890, 2345678901] }

Development Workflow

Use watch mode for fast iteration:

npm run watch

In a second terminal, re-run the built file after each successful compile.

Error Handling

The server throws structured MCP errors using McpError (e.g. InvalidParams, InvalidRequest). Tool failures are returned as JSON blocks: { "success": false, "error": "message" }.

Fuzzy Product Title Matching

If title lookup fails, a broader search computes a similarity score using Levenshtein distance; products below 0.5 similarity threshold are rejected to avoid incorrect matches.

Security Notes

• Only GraphQL & REST calls to your Shopify store (no eval except isolated arithmetic in other demo server).
• Avoid exposing the access token—store it in environment variables, not committed files.

Extending

Add a new tool:

1. Add schema in the ListToolsRequestSchema handler array.
2. Add a case branch in the CallToolRequestSchema switch.
3. Return pretty-printed JSON (JSON.stringify(data, null, 2)).
4. Rebuild & restart.

Troubleshooting

| Symptom | Check | |---------|-------| | Missing data / 400 errors | Verify required scopes on access token | | "Missing Shopify configuration" | Ensure both env vars exported in the same shell session | | Fuzzy title not found | Similarity < 0.5; try an id or handle | | Empty search results | Adjust query syntax; category filter adds (product_type:... OR tag:...) |

License

MIT

For publishing to npm: ensure you rename this file to README.md, add a proper repository field, and include files whitelist (e.g. ["build","README.md","LICENSE"]).