AntonAndrusenko/shopify-mcp-admin

@anton.andrusenko/shopify-mcp-admin

🛍️ MCP Server for Shopify Admin API — Enable AI agents to manage Shopify stores with 40 powerful tools

✨ Features

• 🛠️ 40 MCP Tools — Complete store management: products, inventory, collections, pages, blogs, redirects
• 🤖 AI-Optimized — Tool descriptions and error messages designed for LLM comprehension
• 🔌 Dual Transport — STDIO for Claude Desktop, HTTP for ChatGPT/OpenAI
• ⚡ Rate Limiting — Automatic retry with exponential backoff for Shopify API limits
• 🔒 Secure — Tokens never exposed to AI agents; validated environment configuration

🚀 Quick Start

Prerequisites

1. Node.js 20+ — Download
2. Shopify Custom App — Create one in your Shopify Admin:
   • Go to Settings → Apps and sales channels → Develop apps
   • Create a new app and configure Admin API scopes (see Required Scopes)
   • Install the app and copy the Admin API access token

Installation

# Run directly with npx (recommended)
npx @anton.andrusenko/shopify-mcp-admin

# Or install globally
npm install -g @anton.andrusenko/shopify-mcp-admin

Configuration

Set your environment variables:

export SHOPIFY_STORE_URL=your-store.myshopify.com
export SHOPIFY_ACCESS_TOKEN=shpat_xxxxx

First Tool Invocation

Once connected to an AI agent, try:

"List all products in my Shopify store"

The AI will use the list-products tool to fetch your catalog.

⚙️ Configuration Reference

Required Shopify Scopes

Configure these scopes when creating your Custom App:

📖 Setup Guide: Shopify Custom App Documentation

🖥️ Claude Desktop Integration

Step 1: Configure Claude Desktop

Edit your Claude Desktop configuration file:

• macOS: ~/.config/claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 2: Add the MCP Server

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["@anton.andrusenko/shopify-mcp-admin"],
      "env": {
        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Quit and reopen Claude Desktop. You should see "shopify" in the MCP servers list.

Common Issues

🌐 OpenAI/ChatGPT Integration

For OpenAI function calling or ChatGPT plugins, use HTTP transport mode.

Step 1: Start the Server

TRANSPORT=http \
PORT=3000 \
SHOPIFY_STORE_URL=your-store.myshopify.com \
SHOPIFY_ACCESS_TOKEN=shpat_xxxxx \
npx @anton.andrusenko/shopify-mcp-admin

Step 2: Test the Connection

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Step 3: Call a Tool

# Example: List products
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list-products",
      "arguments": { "first": 10 }
    },
    "id": 2
  }'

OpenAI Function Calling Format

Each tool can be converted to OpenAI function format:

{
  "name": "list-products",
  "description": "List products from the Shopify store with optional filtering",
  "parameters": {
    "type": "object",
    "properties": {
      "first": { "type": "number", "description": "Number of products to return" },
      "query": { "type": "string", "description": "Search query" }
    }
  }
}

🛠️ Available Tools

@anton.andrusenko/shopify-mcp-admin provides 40 tools organized into 7 categories:

🔧 Troubleshooting

Common Errors

Debug Mode

Enable verbose logging to diagnose issues:

# Option 1: DEBUG flag
DEBUG=1 npx @anton.andrusenko/shopify-mcp-admin

# Option 2: LOG_LEVEL
LOG_LEVEL=debug npx @anton.andrusenko/shopify-mcp-admin

FAQ

Q: Can I connect to multiple stores?
A: Run separate server instances with different credentials.

Q: Does this work with development stores?
A: Yes, development stores work with Custom Apps.

Q: How do I test without affecting production?
A: Use a development store for testing.

Q: Where can I report bugs?
A: Open an issue on GitHub Issues.

🔄 CI/CD Pipeline

This project uses GitHub Actions for continuous integration and automated releases.

Continuous Integration

Every push to main and every pull request triggers the CI workflow:

# Runs on Node.js 20.x and 22.x
npm ci        # Install dependencies
npm run lint  # Biome linting
npm run typecheck  # TypeScript type checking
npm run test  # Vitest unit tests
npm run build # Production build

All checks must pass before merging pull requests.

Automated Releases

To publish a new version to npm:

# 1. Update version (creates git tag automatically)
npm version patch  # or minor, or major

# 2. Push commit and tag
git push origin main --follow-tags

The release workflow automatically:

1. Runs all CI checks
2. Publishes to npm with provenance
3. Tags the npm package to match the git tag

Repository Setup (for Maintainers)

Required Secrets

Configure these in Settings → Secrets and variables → Actions:

Branch Protection (Recommended)

Enable these settings for the main branch in Settings → Branches:

• ✅ Require a pull request before merging
• ✅ Require status checks to pass before merging
  • Select: build (20.x) and build (22.x)
• ✅ Require branches to be up to date before merging

🤝 Contributing

Contributions are welcome! Here's how to get started:

Development Setup

# Clone the repository
git clone https://github.com/AntonAndrusenko/shopify-mcp-admin.git
cd shopify-mcp-admin

# Install dependencies
npm install

# Run in development mode
npm run dev

Available Scripts

Pull Request Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run npm run lint && npm run test
5. Commit with conventional commits (feat:, fix:, docs:, etc.)
6. Open a Pull Request

Code Style

This project uses Biome for linting and formatting. Configuration is in biome.json.

📜 License

This project is licensed under the MIT License — see the file for details.

🙏 Acknowledgments

• Model Context Protocol by Anthropic
• Shopify Admin API
• Built with TypeScript, Express, and Zod

Made with ❤️ for the AI-powered commerce era