sunny-chowdhury/shopify-mcp-server

Shopify MCP Server (Introspection-Enabled)

1. Overview

Shopify MCP Server is a Model Context Protocol (MCP) server implementation that connects AI assistants like Claude to Shopify store data. This version features automatic schema introspection, which dynamically generates tools based on Shopify's current GraphQL API schema.

The MCP (Model Context Protocol) is an open standard developed by Anthropic that enables AI assistants to interact with external systems and data sources. This implementation specifically focuses on Shopify integration with automatic capabilities that include:

• Dynamic tool generation from Shopify's GraphQL schema
• Automatic API updates when Shopify releases new features
• Schema caching for improved performance
• Complete API coverage for products, customers, orders, and more
• Type-safe operations generated from schema introspection

This framework demonstrates how to build maintainable MCP servers that automatically stay current with evolving APIs, making it an excellent reference for building similar integrations.

2. Architecture Description

The project follows a modular architecture to promote maintainability and extensibility:

shopify-mcp-server/
├── src/
│   ├── index.ts                  # Main entry point with introspection
│   ├── config/                   # Configuration and environment setup
│   │   └── index.ts              # Centralized configuration management
│   ├── shopify-api.ts            # Core Shopify GraphQL API client
│   ├── introspection/            # Schema introspection system
│   │   ├── index.ts              # Main introspection manager
│   │   ├── schema-introspector.ts # GraphQL schema fetching and caching
│   │   ├── schema-parser.ts      # Schema parsing and operation extraction
│   │   ├── tool-generator.ts     # Dynamic MCP tool generation
│   │   └── types.ts              # TypeScript interfaces
│   └── tools-backup/             # Original manual tools (reference)
├── cache/                        # Schema cache (git-ignored)
├── .env                          # Environment variables (not checked into git)
├── .env.example                  # Example environment variables
├── package.json                  # Project dependencies and scripts
└── tsconfig.json                 # TypeScript configuration

Key Components:

• src/index.ts: The entry point that initializes the MCP server with automatic schema introspection and tool generation.

• src/config/index.ts: Centralized configuration management for Shopify API credentials and introspection settings.

• src/shopify-api.ts: Core GraphQL client for executing queries against the Shopify Admin API.

• src/introspection/: The introspection system that automatically generates tools:

  • schema-introspector.ts: Fetches and caches Shopify's GraphQL schema via introspection queries
  • schema-parser.ts: Parses the schema to extract available operations, parameters, and types
  • tool-generator.ts: Dynamically generates MCP tools from parsed schema operations
  • index.ts: Orchestrates the introspection process and tool registration

How Introspection Works:

1. Schema Fetching: On startup, the server queries Shopify's GraphQL introspection endpoint to get the complete API schema
2. Caching: The schema is cached locally with configurable TTL to avoid repeated fetches
3. Parsing: The schema is analyzed to extract all available Query and Mutation operations
4. Tool Generation: Each operation becomes an MCP tool with automatically generated parameter validation and response formatting
5. Registration: Tools are registered with the MCP server and become available to AI assistants

3. Deployment and Testing

Prerequisites

Before you begin, ensure you have:

• Node.js v14 or higher installed
• npm or Yarn package manager
• A Shopify store with Admin API access
• A Shopify API key and secret

Setup

1. Clone the repository:

   git clone https://github.com/your-organization/shopify-mcp-server.git
   cd shopify-mcp-server
   

2. Install dependencies:

   npm install
   

3. Copy the example environment file and fill in your credentials:

   cp .env.example .env
   

4. Edit the .env file with your Shopify API credentials:

   SHOPIFY_SHOP_URL=your-store.myshopify.com
   SHOPIFY_API_KEY=your_api_key
   SHOPIFY_API_SECRET_KEY=your_api_secret_key
   SHOPIFY_ACCESS_TOKEN=your_access_token
   

Building the Server

npm run build

This will compile the TypeScript code into JavaScript in the build directory.

Testing with Claude Desktop

1. Find the Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/config.json
   • Windows: %APPDATA%\Claude\config.json

2. Add your MCP server configuration:

   {
     "mcpServers": {
       "shopify-mcp": {
         "command": "node",
         "args": ["/absolute/path/to/your/shopify-mcp-server/build/index.js"],
         "env": {
           "SHOPIFY_SHOP_URL": "your-store.myshopify.com",
           "SHOPIFY_ACCESS_TOKEN": "your_access_token",
           "SHOPIFY_API_VERSION": "2023-04"
         }
       }
     }
   }
   

3. Restart Claude Desktop.

4. Start a new conversation in Claude Desktop and click on the MCP icon (plug symbol) to enable your Shopify MCP server.

5. Test with queries like:

   • "Show me the top-selling products in my Shopify store"
   • "Get me a list of recent orders"
   • "How many customers do I have?"

Testing with MCP Inspector

For development purposes, you can use the MCP Inspector tool to test your server without Claude Desktop:

npx @modelcontextprotocol/inspector node /path/to/your/build/index.js

This will start a web interface at http://localhost:5173 where you can interact with your MCP server directly.

Adding New Tools

To extend the server with new capabilities:

1. Create a new file in the src/tools/ directory for your domain.
2. Implement your tool functions using the MCP SDK.
3. Register your tools in src/index.ts.

Example:

// src/tools/my-custom-tools.ts
import { z } from 'zod';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

export function registerMyCustomTools(server: McpServer): void {
  server.tool(
    'my-custom-tool',
    {
      param1: z.string().describe('Description of parameter 1'),
      param2: z.number().optional().describe('Optional parameter description'),
    },
    async ({ param1, param2 = 0 }) => {
      // Tool implementation
      return {
        content: [{ type: 'text', text: `Processed ${param1} with value ${param2}` }],
      };
    }
  );
}

// Then in src/index.ts
import { registerMyCustomTools } from './tools/my-custom-tools.js';
// ...
registerMyCustomTools(server);

Contributing

When adding new tools or functionality to this MCP server:

1. Follow the existing modular architecture
2. Add appropriate error handling
3. Document your tools with clear descriptions
4. Update tests if applicable
5. Ensure secure handling of credentials and data

License

This project is intended for internal use within our organization.