bhavik-dreamz/shopify-mcp-server-graphql

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

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

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 john@example.com" (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": "buyer@example.com" }

// 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

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"]).