Shopify Storefront MCP Server

1# Shopify Storefront MCP Server
2 
3This server provides access to the Shopify Storefront API via MCP, allowing AI assistants to query and interact with your Shopify store data.
4 
5## Features
6 
7- Access to product, collection, and inventory data
8- Cart creation and management
9- Support for GraphQL queries and mutations
10- Automatic token handling and validation
11- Easy integration with MCP-compatible AI assistants
12 
13## Setup Instructions
14 
151. Clone this repository
162. Install dependencies: `pip install -r requirements.txt`
173. Copy `.env.example` to `.env` and configure your environment variables
184. Generate a Storefront API token via Shopify Admin (see below)
195. Run the server: `python -m shopify_storefront_mcp_server`
20 
21## Environment Variables
22 
23Create a `.env` file using the provided `.env.example` as a template:
24 
25```
26# Required
27SHOPIFY_STOREFRONT_ACCESS_TOKEN=your_storefront_token
28SHOPIFY_STORE_NAME=your-store-name
29 
30# Optional
31SHOPIFY_API_VERSION=2025-04
32SHOPIFY_BUYER_IP=127.0.0.1
33```
34 
35## Generating a Storefront API Token
36 
371. Log in to your Shopify admin
382. Go to **Apps and sales channels** > **Develop apps** > **Create an app**
393. Name your app (e.g., "MCP Storefront")
404. Go to **API credentials** > **Configure Storefront API scopes**
415. Select necessary scopes:
42   - `unauthenticated_read_product_listings`
43   - `unauthenticated_read_product_inventory`
44   - `unauthenticated_read_product_pricing`
45   - `unauthenticated_write_checkouts`
46   - `unauthenticated_read_content`
476. Save and copy the generated Storefront API access token
487. Add the token to your `.env` file as `SHOPIFY_STOREFRONT_ACCESS_TOKEN`
49 
50## Usage Examples
51 
52Running with the MCP server:
53 
54```
55python -m shopify_storefront_mcp_server
56```
57 
58The server exposes the following MCP tools:
59 
60- `shopify_discover`: Detect if a URL belongs to a Shopify storefront and discover authentication tokens
61- `shopify_storefront_graphql`: Execute GraphQL queries against the Storefront API
62- `customer_data`: Unified tool for all customer data operations (Create, Read, Update, Delete)
63 
64### Customer Resources
65 
66This server also provides MCP resources for customer information:
67 
68- `customer://name`: Customer's full name
69- `customer://email`: Customer's email address
70- `customer://phone`: Customer's phone number
71- `customer://shipping_address`: Customer's shipping address (including address1, address2, city, state, postal_code, country)
72- `customer://billing_address`: Customer's billing address (including address1, address2, city, state, postal_code, country)
73- `customer://profile`: Complete customer profile
74 
75Customer data is stored in `user_data/customer.json` and should be managed using the `customer_data` tool.
76 
77### Managing Customer Data
78 
79The server provides a unified `customer_data` tool for managing all customer information. This tool consolidates create, read, update, and delete operations into a single interface.
80 
81Examples:
82 
83```
84# Get all customer data
85customer_data(operation="get")
86 
87# Get a specific field
88customer_data(operation="get", field="name")
89customer_data(operation="get", field="shipping_address")
90 
91# Update a specific field
92customer_data(operation="update", field="name", value="Jane Doe")
93customer_data(
94    operation="update",
95    shipping_address={
96        "address1": "123 Main St",
97        "address2": "Apt 4B",
98        "city": "New York",
99        "state": "NY",
100        "postal_code": "10001",
101        "country": "US"
102    }
103)
104 
105# Add custom fields
106customer_data(
107    operation="update",
108    custom_fields={
109        "preferences": {
110            "theme": "dark",
111            "notifications": "email",
112            "language": "en-US"
113        },
114        "loyalty_tier": "gold",
115        "last_purchase_date": "2023-06-15"
116    }
117)
118 
119# Get a custom field
120customer_data(operation="get", field="preferences")
121customer_data(operation="get", field="loyalty_tier")
122 
123# Update single custom field
124customer_data(operation="update", field="loyalty_tier", value="platinum")
125 
126# Delete a specific field
127customer_data(operation="delete", field="phone")
128customer_data(operation="delete", field="preferences")
129 
130# Delete all customer data
131customer_data(operation="delete")
132```
133 
134This consolidated tool simplifies integration with AI assistants by providing a consistent interface for all customer data operations, including both standard customer information and any custom fields that may be useful for personalization.
135 
136### Data Privacy & Storage
137 
138Customer data is stored in `user_data/customer.json`. This file contains personal information and should not be committed to version control. The repository includes:
139 
140- `user_data/customer.json.example`: A template file showing the expected structure with dummy data
141- Entries in `.gitignore` to prevent accidental commits of actual customer data
142 
143When deploying this server, the `user_data/customer.json` file will be created automatically when the `customer_data` tool is first used. You can also copy and rename the example file to get started:
144 
145```bash
146cp user_data/customer.json.example user_data/customer.json
147```
148 
149All data stored in the customer file persists between server restarts. The file supports both standard customer fields (name, email, addresses) and arbitrary custom fields for AI personalization.
150 
151### Creating Checkouts with Customer Data
152 
153The server makes it easy to create Shopify checkouts that include customer information by combining the `customer_data` and `shopify_storefront_graphql` tools.
154 
155Example workflow:
156 
157```
158# Step 1: Get customer data
159customer_profile = customer_data(operation="get")
160 
161# Step 2: Create a cart with GraphQL
162cart_mutation = """
163mutation createCart($lines: [CartLineInput!]!) {
164  cartCreate(input: {lines: $lines}) {
165    cart {
166      id
167      checkoutUrl
168    }
169    userErrors {
170      field
171      message
172    }
173  }
174}
175"""
176 
177cart_variables = {
178  "lines": [
179    {
180      "merchandiseId": "gid://shopify/ProductVariant/12345678901234",
181      "quantity": 1
182    }
183  ]
184}
185 
186cart_result = shopify_storefront_graphql(
187  mode="execute",
188  host="your-store.myshopify.com",
189  token="your_storefront_token",
190  query=cart_mutation,
191  variables=cart_variables
192)
193 
194# Step 3: Apply customer attributes to the cart
195cart_id = # extract from cart_result
196customer_info = json.loads(customer_profile)
197 
198attributes_mutation = """
199mutation updateCartAttributes($cartId: ID!, $attributes: [AttributeInput!]!) {
200  cartAttributesUpdate(cartId: $cartId, attributes: $attributes) {
201    cart {
202      id
203      checkoutUrl
204    }
205    userErrors {
206      field
207      message
208    }
209  }
210}
211"""
212 
213attributes_variables = {
214  "cartId": cart_id,
215  "attributes": [
216    {
217      "key": "email",
218      "value": customer_info["email"]
219    },
220    {
221      "key": "deliveryAddress",
222      "value": json.dumps(customer_info["shipping_address"])
223    }
224  ]
225}
226 
227shopify_storefront_graphql(
228  mode="execute",
229  host="your-store.myshopify.com",
230  token="your_storefront_token",
231  query=attributes_mutation,
232  variables=attributes_variables
233)
234```
235 
236This approach gives you complete control over the checkout process while leveraging the stored customer information.
237 
238## Troubleshooting
239 
240If you encounter authentication errors:
241 
2421. Verify token format: Storefront API tokens should start with `shpsa_` (newer) or `shpat_` (older)
2432. Check store name: Ensure SHOPIFY_STORE_NAME is correct (without .myshopify.com)
2443. Check API version: Make sure the API version is supported
2454. Test token: Use cURL to test your token directly:
246   ```
247   curl -X POST \
248     https://your-store.myshopify.com/api/2025-04/graphql.json \
249     -H "Content-Type: application/json" \
250     -H "X-Shopify-Storefront-Access-Token: your_token" \
251     -d '{"query": "query { shop { name } }"}'
252   ```
2535. Regenerate token: If issues persist, create a new token with proper scopes
254 
255## Security Considerations
256 
257- Never commit your `.env` file or any files containing API tokens
258- Use environment variables for all sensitive information
259- Consider setting up IP restrictions in your Shopify Admin
260- Review the permissions granted to your Storefront API token
261 
262