shopify-mcp
Shopify Admin MCP server for one store: read tools, plus opt-in allowlisted changes
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/walma-labs--shopify-mcp)HTML
<a href="/listings/walma-labs--shopify-mcp"><img src="/api/listings/walma-labs--shopify-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Create the app
Shopify has two kinds of app that fit. Use the first unless the store already has the second.
**An app in the Dev Dashboard (current).** In the [Dev Dashboard](https://dev.shopify.com/dashboard) of the organisation that owns the store: create an app, give it the access scopes below, release a version and install it on the store. Copy its **Client ID** and **Client secret**. The server trades them for an access token that lasts 24 hours and renews it by itself. This works only when the app and the store are in the **same Shopify organisation**.
**A custom app created in the store admin (legacy).** Settings → Apps and sales channels → Develop apps → the app → API credentials. Its **Admin API access token** (`shpat_…`) does not expire.
2. Access scopes
Grant only what you want the model to be able to read:
| Scope | Needed for | |---|---| | `read_products` | `list_products`, product and collection queries | | `read_orders` | `list_orders` (the last 60 days) | | `read_all_orders` | orders older than 60 days | | `read_reports` | `run_analytics_query` | | `read_inventory`, `read_locations` | inventory per location | | `read_customers` | customer queries. Leave it out to keep personal data out of reach |
Grant a `write_` scope only for what you have switched on under [Writing](#writing). The scopes are the second lock.
3. Add it to your MCP client
**Claude Code:**
claude mcp add shopify --scope user \ -e SHOPIFY_STORE_DOMAIN=example.myshopify.com \ -e SHOPIFY_CLIENT_ID=your-client-id \ -e SHOPIFY_CLIENT_SECRET=your-client-secret \ -- npx -y github:Walma-Labs/shopify-mcp
**Claude Desktop, Cursor and others** (`mcpServers` in the client's config):
{
"mcpServers": {
"shopify": {
"command": "npx",
"args": ["-y", "github:Walma-Labs/shopify-mcp"],
"env": {
"SHOPIFY_STORE_DOMAIN": "example.myshopify.com",
"SHOPIFY_CLIENT_ID": "your-client-id",
"SHOPIFY_CLIENT_SECRET": "your-client-secret"
}
}
}
}What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 142 lines
- # shopify-mcp — Shopify Admin MCP server
- A [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude, Cursor, Claude Code and any other MCP client access to **one Shopify store**: its products, orders and analytics, and any other read query of the Admin GraphQL API. It is read-only by default and can be allowed to make chosen changes.
- - **Read-only unless you switch writing on.** Every query is parsed before it is sent, and anything that is not a pure query is refused. Writing is one extra tool that exists only when `SHOPIFY_WRITE_TOOLS` is set, limited to an allowlist of mutations (see [Writing](#writing)). On top of that, the store decides what the app may touch through its access scopes.
- - **One store, one credential.** The server is bound to a single store and uses that store's own app. It never holds a user's login.
- - **Streamable HTTP as well as stdio.** It can run centrally. This is how [Walma](https://walma.ai) serves it to whole organisations through its AI gateway.
- - **Three runtime dependencies.** It calls the Admin GraphQL API directly.
- Built and used by [Walma AI](https://walma.ai).
- ## Tools
- | Tool | What it does |
- |---|---|
- | `get_shop` | The store, its currency and time zone, and the access scopes the app was granted |
- | `list_products` | Products with status, vendor, type, tags, total inventory and price range; search filter, sorting, paging |
- | `list_orders` | Orders with dates, payment and fulfilment status, totals and line items; search filter, sorting, paging |
- | `run_analytics_query` | A ShopifyQL query (`FROM sales SHOW total_sales GROUP BY month SINCE -12m`) |
- | `graphql_introspect` | One type of the Admin schema: fields, arguments, enum values |
- | `graphql_query` | Any single read query, for what the other tools do not cover |
- `list_orders` returns no customer, address or e-mail fields. A caller who needs them can ask through `graphql_query`, and gets them only if the store granted the app the customer scopes.
- ## Writing
- Set `SHOPIFY_WRITE_TOOLS=1` and the server gains a seventh tool, `graphql_mutation`, which runs one mutation. **It changes the live store at once**: Shopify has no dry run and no undo, so have your MCP client ask before each call.
- A mutation is sent only if it passes all of this, checked in the server whatever the model is asked to do:
- 1. **It is on the allowlist.** By default: pages, blog posts, redirects, discounts, metaobjects and metafields, files, menus and marketing activities, which is what campaign work needs. Not products, prices, inventory, orders or customers.
- 2. **A delete is allowed only by its exact name.** `page*` lets `pageCreate` and `pageUpdate` through, never `pageDelete`.
- 3. **It is not on the hard-deny list.** Refunds, payments, gift cards, cancelling or creating orders, staff, access tokens, webhooks, customer deletion and data erasure, bulk mutations, and publishing or deleting a theme are refused whatever the allowlist says.
- Change the allowlist with `SHOPIFY_ALLOWED_MUTATIONS`, a comma-separated list of mutation names or prefixes ending in `*`. It replaces the default:
- ```sh
- SHOPIFY_ALLOWED_MUTATIONS="page*,discountCode*,productUpdate,pageDelete"
- ```
- The app also needs the matching `write_` scopes (`write_content` or `write_online_store_pages` for pages, `write_discounts` for discounts, and so on). Grant only those.
- Shopify reports a refused mutation as `userErrors` in an otherwise successful answer. The tool returns that as an error, so a change that did not happen is not read as done.
- Every caller writes as the same app, so the store's activity log shows the app, not the person.
- ## Setup
- ### 1. Create the app
- Shopify has two kinds of app that fit. Use the first unless the store already has the second.
- **An app in the Dev Dashboard (current).** In the [Dev Dashboard](https://dev.shopify.com/dashboard) of the organisation that owns the store: create an app, give it the access scopes below, release a version and install it on the store. Copy its **Client ID** and **Client secret**. The server trades them for an access token that lasts 24 hours and renews it by itself. This works only when the app and the store are in the **same Shopify organisation**.
- **A custom app created in the store admin (legacy).** Settings → Apps and sales channels → Develop apps → the app → API credentials. Its **Admin API access token** (`shpat_…`) does not expire.
- ### 2. Access scopes
- Grant only what you want the model to be able to read:
- | Scope | Needed for |
- |---|---|
- | `read_products` | `list_products`, product and collection queries |
- | `read_orders` | `list_orders` (the last 60 days) |
- | `read_all_orders` | orders older than 60 days |
- | `read_reports` | `run_analytics_query` |
- | `read_inventory`, `read_locations` | inventory per location |
- | `read_customers` | customer queries. Leave it out to keep personal data out of reach |
- Grant a `write_` scope only for what you have switched on under [Writing](#writing). The scopes are the second lock.
- ### 3. Add it to your MCP client
- **Claude Code:**
- ```sh
- claude mcp add shopify --scope user \
- -e SHOPIFY_STORE_DOMAIN=example.myshopify.com \
- -e SHOPIFY_CLIENT_ID=your-client-id \
- -e SHOPIFY_CLIENT_SECRET=your-client-secret \
- -- npx -y github:Walma-Labs/shopify-mcp
- ```
- **Claude Desktop, Cursor and others** (`mcpServers` in the client's config):
- ```json
- {
- "mcpServers": {
- "shopify": {
- "command": "npx",
- "args": ["-y", "github:Walma-Labs/shopify-mcp"],
- "env": {
- "SHOPIFY_STORE_DOMAIN": "example.myshopify.com",
- "SHOPIFY_CLIENT_ID": "your-client-id",
- "SHOPIFY_CLIENT_SECRET": "your-client-secret"
- }
- }
- }
- }
- ```
- ## Configuration
- | Variable | |
- |---|---|
- | `SHOPIFY_STORE_DOMAIN` | Required. `example` or `example.myshopify.com`. Only `*.myshopify.com` is accepted, so the token cannot be sent to another host |
- | `SHOPIFY_CLIENT_ID`, `SHOPIFY_CLIENT_SECRET` | A Dev Dashboard app. Wins when the static token is also set |
- | `SHOPIFY_ACCESS_TOKEN` | A legacy custom app's Admin API token |
- | `SHOPIFY_WRITE_TOOLS` | Optional: `1` registers `graphql_mutation`. See [Writing](#writing) |
- | `SHOPIFY_ALLOWED_MUTATIONS` | Optional: which mutations, replacing the default list |
- | `SHOPIFY_API_VERSION` | Optional, default `2026-10`. Shopify supports a version for at least a year |
- ## Running over HTTP
- ```sh
- npm run build
- PORT=8080 npm run start:http
- ```
- `POST /` is the MCP endpoint (streamable HTTP, stateless) and `GET /healthz` answers `ok`. There is **no authentication** in this process: put it behind something that authenticates callers. Everyone who can reach it reads the store with the app's scopes.
- ## Using it as a library
- ```ts
- import { createShopifyClient, createShopifyServer } from "@walma-labs/shopify-mcp";
- const client = createShopifyClient(); // built once; caches the store's access token
- const server = createShopifyServer(client); // a fresh McpServer per request
- ```
- ## Development
- ```sh
- npm install
- npm test
- ```
- The tests drive the real MCP wire against a mocked HTTP function, so they need neither network nor a store. The built-in queries are validated against a copy of the parts of the Admin schema they use (`test/logic.spec.ts`); update both together when Shopify renames a field.
- ## Licence
- Apache-2.0.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.