Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/walma-labs--shopify-mcp/badge.svg)](/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

i

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
  1. # shopify-mcp — Shopify Admin MCP server
  2. 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.
  3. - **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.
  4. - **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.
  5. - **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.
  6. - **Three runtime dependencies.** It calls the Admin GraphQL API directly.
  7. Built and used by [Walma AI](https://walma.ai).
  8. ## Tools
  9. | Tool | What it does |
  10. |---|---|
  11. | `get_shop` | The store, its currency and time zone, and the access scopes the app was granted |
  12. | `list_products` | Products with status, vendor, type, tags, total inventory and price range; search filter, sorting, paging |
  13. | `list_orders` | Orders with dates, payment and fulfilment status, totals and line items; search filter, sorting, paging |
  14. | `run_analytics_query` | A ShopifyQL query (`FROM sales SHOW total_sales GROUP BY month SINCE -12m`) |
  15. | `graphql_introspect` | One type of the Admin schema: fields, arguments, enum values |
  16. | `graphql_query` | Any single read query, for what the other tools do not cover |
  17. `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.
  18. ## Writing
  19. 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.
  20. A mutation is sent only if it passes all of this, checked in the server whatever the model is asked to do:
  21. 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.
  22. 2. **A delete is allowed only by its exact name.** `page*` lets `pageCreate` and `pageUpdate` through, never `pageDelete`.
  23. 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.
  24. Change the allowlist with `SHOPIFY_ALLOWED_MUTATIONS`, a comma-separated list of mutation names or prefixes ending in `*`. It replaces the default:
  25. ```sh
  26. SHOPIFY_ALLOWED_MUTATIONS="page*,discountCode*,productUpdate,pageDelete"
  27. ```
  28. 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.
  29. 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.
  30. Every caller writes as the same app, so the store's activity log shows the app, not the person.
  31. ## Setup
  32. ### 1. Create the app
  33. Shopify has two kinds of app that fit. Use the first unless the store already has the second.
  34. **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**.
  35. **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.
  36. ### 2. Access scopes
  37. Grant only what you want the model to be able to read:
  38. | Scope | Needed for |
  39. |---|---|
  40. | `read_products` | `list_products`, product and collection queries |
  41. | `read_orders` | `list_orders` (the last 60 days) |
  42. | `read_all_orders` | orders older than 60 days |
  43. | `read_reports` | `run_analytics_query` |
  44. | `read_inventory`, `read_locations` | inventory per location |
  45. | `read_customers` | customer queries. Leave it out to keep personal data out of reach |
  46. Grant a `write_` scope only for what you have switched on under [Writing](#writing). The scopes are the second lock.
  47. ### 3. Add it to your MCP client
  48. **Claude Code:**
  49. ```sh
  50. claude mcp add shopify --scope user \
  51. -e SHOPIFY_STORE_DOMAIN=example.myshopify.com \
  52. -e SHOPIFY_CLIENT_ID=your-client-id \
  53. -e SHOPIFY_CLIENT_SECRET=your-client-secret \
  54. -- npx -y github:Walma-Labs/shopify-mcp
  55. ```
  56. **Claude Desktop, Cursor and others** (`mcpServers` in the client's config):
  57. ```json
  58. {
  59. "mcpServers": {
  60. "shopify": {
  61. "command": "npx",
  62. "args": ["-y", "github:Walma-Labs/shopify-mcp"],
  63. "env": {
  64. "SHOPIFY_STORE_DOMAIN": "example.myshopify.com",
  65. "SHOPIFY_CLIENT_ID": "your-client-id",
  66. "SHOPIFY_CLIENT_SECRET": "your-client-secret"
  67. }
  68. }
  69. }
  70. }
  71. ```
  72. ## Configuration
  73. | Variable | |
  74. |---|---|
  75. | `SHOPIFY_STORE_DOMAIN` | Required. `example` or `example.myshopify.com`. Only `*.myshopify.com` is accepted, so the token cannot be sent to another host |
  76. | `SHOPIFY_CLIENT_ID`, `SHOPIFY_CLIENT_SECRET` | A Dev Dashboard app. Wins when the static token is also set |
  77. | `SHOPIFY_ACCESS_TOKEN` | A legacy custom app's Admin API token |
  78. | `SHOPIFY_WRITE_TOOLS` | Optional: `1` registers `graphql_mutation`. See [Writing](#writing) |
  79. | `SHOPIFY_ALLOWED_MUTATIONS` | Optional: which mutations, replacing the default list |
  80. | `SHOPIFY_API_VERSION` | Optional, default `2026-10`. Shopify supports a version for at least a year |
  81. ## Running over HTTP
  82. ```sh
  83. npm run build
  84. PORT=8080 npm run start:http
  85. ```
  86. `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.
  87. ## Using it as a library
  88. ```ts
  89. import { createShopifyClient, createShopifyServer } from "@walma-labs/shopify-mcp";
  90. const client = createShopifyClient(); // built once; caches the store's access token
  91. const server = createShopifyServer(client); // a fresh McpServer per request
  92. ```
  93. ## Development
  94. ```sh
  95. npm install
  96. npm test
  97. ```
  98. 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.
  99. ## Licence
  100. Apache-2.0.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.