Shopify_store-MCP: Instructions file for Claude Code

Shopify Store MCP Server

An MCP server that connects to live Shopify stores via Admin and Storefront APIs.

Quick Reference

npm run build      # Compile TypeScript + generate Prisma
npm run dev        # Watch mode
npm run inspect    # MCP Inspector for testing
npm run db:studio  # Browse SQLite database

Architecture

Two-Tier Tool Design

1. run_graphql_query — Universal escape hatch for ANY Shopify GraphQL operation
2. Smart tools — Multi-step workflows (polling, staged uploads, bulk ops)

Don't create per-resource CRUD tools. Shopify has hundreds of operations. Use run_graphql_query for simple operations, smart tools for complex workflows.

Current Tools (11)

Tool	Type	Purpose
get_shop_info	Core	Store configuration
run_graphql_query	Core	Execute any GraphQL
upload_file	Smart	URL/path/base64 → poll → CDN URL
bulk_export	Smart	Bulk query → JSONL URL
bulk_import	Smart	Staged upload → bulk mutation
upsert_metaobject	Smart	Idempotent create/update
delete_metaobject	Smart	Delete by ID or type+handle
schema_discover	Smart	Metafield/metaobject definitions
configure	Infra	Set rate limit tier
get_history	Infra	Query past operations
get_stats	Infra	Usage statistics

Critical Patterns

Git Commits

NEVER add Co-Authored-By lines to commits. Do not attribute commits to Claude or any AI assistant.

Never use console.log

STDIO transport uses stdout for MCP protocol. Always use console.error:

console.error("[shopify-store-mcp] Log message");  // Good
console.log("Log message");  // BREAKS MCP PROTOCOL

ES Module imports

Use .js extension in all imports:

import { foo } from "./foo.js";  // Good
import { foo } from "./foo";     // Bad

Error handling

Use utilities from errors.ts:

import { formatSuccessResponse, formatErrorResponse, formatGraphQLErrors, formatUserErrors } from "../errors.js";

// In tool handler
if (response.errors) return formatGraphQLErrors(response);
if (userErrors?.length) return formatUserErrors(userErrors);
return formatSuccessResponse(data);