Store Chat MCP Server

An MCP (Model Context Protocol) server that enables Claude Desktop to interact with Shopify stores using the public Storefront API.

Features

• Store Code Based Access: Use store codes instead of domains for enhanced security
• Subscription Validation: Automatic checking of store subscription status
• Analytics Tracking: All tool executions are tracked for usage insights
• No Authentication Required: Uses Shopify's public Storefront API
• Rich Store Interactions: Search products, check inventory, browse collections
• Real-time Data: Direct connection to live Shopify stores
• TypeScript Support: Fully typed for better development experience
• Backward Compatibility: Still supports legacy domain-based access

Available Tools

1. search_products

Search for products in a Shopify store.

Parameters:

• storeCode (recommended): The store code (e.g., ABCD-1234)
• domain (deprecated): The Shopify store domain (for backward compatibility)
• query (required): Search query to find products
• limit (optional): Maximum number of products to return (default: 10, max: 250)

2. get_product

Get detailed information about a specific product.

Parameters:

• storeCode (recommended): The store code (e.g., ABCD-1234)
• domain (deprecated): The Shopify store domain (for backward compatibility)
• productId (required): The product ID (Shopify GID) or handle (URL slug)

3. check_inventory

Check inventory levels for a specific product variant.

Parameters:

• storeCode (recommended): The store code (e.g., ABCD-1234)
• domain (deprecated): The Shopify store domain (for backward compatibility)
• variantId (required): The variant ID to check inventory for

4. get_store_info

Get general information about the Shopify store.

Parameters:

• storeCode (recommended): The store code (e.g., ABCD-1234)
• domain (deprecated): The Shopify store domain (for backward compatibility)

5. list_collections

List product collections in the store.

Parameters:

• storeCode (recommended): The store code (e.g., ABCD-1234)
• domain (deprecated): The Shopify store domain (for backward compatibility)
• limit (optional): Maximum number of collections to return (default: 10, max: 250)

Installation

npm install @store-chat/mcp-server

Usage with Claude Desktop

1. Add the server to your Claude Desktop configuration:

{
  "mcpServers": {
    "store-chat": {
      "command": "npx",
      "args": ["@store-chat/mcp-server"]
    }
  }
}

2. Restart Claude Desktop

3. Start chatting with any Shopify store:

Using store codes (recommended):

"Search for t-shirts using store code ABCD-1234"
"Show me the collections for store WXYZ-5678"
"Check if variant gid://shopify/ProductVariant/123 is in stock for store ABCD-1234"

Using domains (legacy):

"Search for t-shirts in the quickstart-6f5d3a6e.myshopify.com store"
"Show me the collections available"
"Check if variant gid://shopify/ProductVariant/123 is in stock"

Configuration

Set the following environment variables for the MCP server:

# API endpoint configuration (required for store code validation)
STORE_CHAT_API_URL=https://your-app.myshopify.com

# API secret for authentication (required)
ANALYTICS_API_SECRET=your-secret-key

# Optional: Custom analytics API key
ANALYTICS_API_KEY=your-api-key

Development

Setup

# Clone the repository
git clone <repository-url>

# Navigate to the MCP server package
cd packages/mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Testing

# Run tests
npm test

# Run linting
npm run lint

# Type checking
npm run typecheck

Project Structure

src/
├── index.ts               # Main server entry point
├── config.ts              # Configuration management
├── api/
│   └── client.ts          # API client for validation & analytics
├── middleware/
│   └── store-validation.ts # Store validation middleware
├── shopify/
│   └── client.ts          # Shopify Storefront API client
├── tools/
│   ├── index.ts           # Tool exports
│   ├── search-products.ts
│   ├── get-product.ts
│   ├── check-inventory.ts
│   ├── get-store-info.ts
│   └── list-collections.ts
└── utils/
    └── logger.ts          # Winston logger configuration

Example Store for Testing

You can test the MCP server with this example Shopify store:

• Domain: quickstart-6f5d3a6e.myshopify.com

This is a public demo store that's perfect for testing all the available tools.

How It Works

1. Store Validation: When a tool is called with a store code, the server validates it with the main app API
2. Subscription Check: The server verifies the store has an active subscription (ACTIVE or TRIAL status)
3. Tool Execution: If validation passes, the requested operation is performed using the store's domain
4. Analytics Tracking: After execution, usage analytics are sent back to the main app

Error Handling

The server includes comprehensive error handling:

• Invalid store codes are validated and reported
• Expired subscriptions block access with clear messages
• Invalid store domains are caught and reported
• Network errors are logged and returned as user-friendly messages
• GraphQL errors are parsed and displayed clearly
• All errors include context for debugging

Logging

The server uses Winston for structured logging:

• Set LOG_LEVEL environment variable to control verbosity
• Logs include timestamps, error stacks, and request context
• Console output is colorized for better readability

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT

Support

For issues, questions, or contributions, please visit the GitHub repository.