Full Shopify Admin API Coverage: Products, Orders, Customers, Inventory, Collections, and more
GraphQL Support: Execute GraphQL Admin API queries
Automatic Rate Limiting: Intelligent retry with exponential backoff
Type-Safe: Comprehensive TypeScript types for all Shopify entities
Cursor-Based Pagination: Automatic handling of paginated responses
MCP Resources: UI-friendly resource endpoints for apps
Dual Transport: Stdio (default) or HTTP/SSE modes

Installation

npm install
npm run build

Configuration

Environment Variables

Variable	Required	Description	Example
`SHOPIFY_ACCESS_TOKEN`	✅	Admin API access token	`shpat_xxxxxxxxxxxxx`
`SHOPIFY_STORE`	✅	Store name (without .myshopify.com)	`my-store`
`SHOPIFY_API_VERSION`	❌	API version (default: 2024-01)	`2024-01`
`DEBUG`	❌	Enable debug logging	`true`

Getting Your Access Token

Go to your Shopify admin: https://your-store.myshopify.com/admin
Navigate to Settings → Apps and sales channels → Develop apps
Click Create an app or select an existing one
Go to API credentials tab
Click Install app (if not already installed)
Copy the Admin API access token (starts with shpat_)

Required API Scopes

Grant the following scopes to your app (based on features needed):

read_products, write_products - Product management
read_orders, write_orders - Order management
read_customers, write_customers - Customer management
read_inventory, write_inventory - Inventory tracking
read_content, write_content - Pages, blogs, themes
read_discounts, write_discounts - Price rules and discount codes
read_shipping, write_shipping - Shipping zones and carriers
read_analytics - Analytics and reports

Usage

Stdio Mode (Default)

# Copy example env file
cp .env.example .env

# Edit .env with your credentials
# SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxx
# SHOPIFY_STORE=your-store-name

# Start the server
npm start

# Or in development mode with auto-reload
npm run dev

HTTP Mode

# Start with HTTP transport
npm start -- --http --port=3000

# Health check
curl http://localhost:3000/health

Available Tools

The server provides the following tool categories (lazy-loaded on demand):

Products

Create, read, update, delete products
Manage variants and images
Bulk operations

Orders

List and search orders
Update order status
Create refunds
Manage fulfillments

Customers

Customer CRUD operations
Customer search
Manage addresses

Inventory

Track inventory levels
Manage locations
Adjust stock quantities

Collections

Smart and custom collections
Add/remove products from collections

Discounts

Create price rules
Generate discount codes
Manage promotions

Fulfillments

Create fulfillments
Update tracking information
Cancel fulfillments

Shipping

Shipping zones
Carrier services
Delivery profiles

Themes

Theme management
Asset upload/download

Content

Pages
Blogs and articles
Redirects

Webhooks

Register webhooks
Manage subscriptions

Analytics

Sales reports
Product analytics
Customer insights

MCP Resources

Resources are available for UI applications:

shopify://products - List all products
shopify://orders - List all orders
shopify://customers - List all customers
shopify://inventory - View inventory levels

API Client Features

Rate Limiting

The client automatically handles Shopify's rate limits:

Parses X-Shopify-Shop-Api-Call-Limit header
Warns when approaching limit (80%+ used)
Automatic retry with exponential backoff (1s, 2s, 4s)

Pagination

// Get single page
const { data, pageInfo } = await client.list('/products.json');

// Get all pages (with safety limit)
const allProducts = await client.listAll('/products.json', {}, 10);

GraphQL

const result = await client.graphql(`
  query {
    products(first: 10) {
      edges {
        node {
          id
          title
          handle
        }
      }
    }
  }
`);

Error Handling

All errors are normalized with structured responses:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Shopify API rate limit exceeded. Please retry after a delay."
}

Error codes:

TOOL_NOT_FOUND - Requested tool doesn't exist
RESOURCE_READ_ERROR - Failed to read resource
AUTHENTICATION_ERROR - Invalid access token
RATE_LIMIT_EXCEEDED - Too many requests
UNKNOWN_ERROR - Unexpected error

Development

# Install dependencies
npm install

# Run TypeScript compiler in watch mode
npx tsc --watch

# Run development server with auto-reload
npm run dev

# Type check only (no build)
npx tsc --noEmit

# Build for production
npm run build

Architecture

src/
├── main.ts              # Entry point, env validation, transports
├── server.ts            # MCP server setup, handlers
├── clients/
│   └── shopify.ts       # Shopify API client (REST + GraphQL)
├── types/
│   └── index.ts         # TypeScript interfaces for Shopify entities
├── tools/               # Tool modules (created separately)
│   ├── products.ts
│   ├── orders.ts
│   ├── customers.ts
│   └── ...
└── apps/                # UI applications (created separately)

Troubleshooting

"Authentication failed"

Verify SHOPIFY_ACCESS_TOKEN is correct
Ensure the app is installed on your store
Check that the token hasn't been revoked

"Resource not found"

Check that SHOPIFY_STORE is correct (without .myshopify.com)
Verify the resource ID exists in your store

"Rate limit exceeded"

The client will automatically retry with backoff
Consider implementing request batching for bulk operations
Monitor rate limit info with client.getRateLimitInfo()

TypeScript errors

Run npm install to ensure all dependencies are installed
Check that @types/node version matches your Node.js version
Verify tsconfig.json settings

License

MIT

Support

For issues and questions:

GitHub Issues: mcpengine repository
Shopify API Docs: https://shopify.dev/docs/api/admin-rest