# Shopify Store Tools



https://github.com/user-attachments/assets/fed59146-c1b3-47ce-88ff-3bf0cfb91750



<p align="center">
  <strong>Bring your Shopify store into your agent's workspace.</strong><br>
  MCP tools for store operations, paired with a portable skill that explains how to use them.
</p>

<p align="center">
  <a href="#get-started">Get started</a> ·
  <a href="docs/clients.md">Connect your agent</a> ·
  <a href="#give-your-agent-the-workflow">Install the skill</a> ·
  <a href="docs/tools.md">Explore the tools</a>
</p>

---

## What you can do

57 Shopify tools for your agent, connected directly to your store. Credentials stay in your local MCP configuration.

| Work on | What your agent can do |
| :--- | :--- |
| **Catalog** | Read and update products, create drafts, attach images, adjust variant prices and inventory |
| **Storefront** | Work with theme files, images and video, pages, and navigation menus |
| **Operations** | Read customer purchase history, manage supported order actions, fulfill orders, configure basic discounts |
| **Reporting** | Summarize accessible orders or request native Shopify Analytics sales reports |

For example, ask your agent to:

> "Create a draft product from these details and images, then check whether its media finished processing."
>
> "Read the current menu and add this page while preserving every existing item."
>
> "Inspect the homepage banner settings on my draft theme and replace the selected image."

The [tool reference](docs/tools.md) describes exact capabilities and limits.

## Get started

**Requires Node.js 20 or later, npm, and Shopify Admin API credentials.**

### 1. Configure your Shopify app

Copy this line into the app's **Admin API access scopes** field in Shopify Dev Dashboard. This read/write preset covers the current tools with fulfillment at merchant-managed locations:

```text
write_products,write_inventory,read_locations,write_customers,write_orders,write_discounts,write_content,write_online_store_navigation,write_themes,write_files,write_merchant_managed_fulfillment_orders,read_reports
```

Shopify's write scopes also grant read access, so separate matching `read_*` entries are unnecessary. Release the updated app configuration, install or approve its updated access on the store, then reconnect the MCP server.

Theme file changes also require Shopify's theme API exemption. Native sales reports require Level 2 protected customer data access. See [credentials and scopes](docs/credentials.md#copy-and-paste-access-scopes) for these requirements, older orders, and other fulfillment setups.

### 2. Connect your agent

Install and connect your store in one command:

```bash
npx -y shopify-store-tools@latest init
```

The wizard checks your store connection and registers the server with Claude Code, Codex CLI, Gemini CLI, Claude Desktop, Cursor, Windsurf, or VS Code Copilot. Choose **Other** for a manual JSON entry.

The npm package includes the compiled server, the portable skill, and its references. You do not need to clone the repository or compile TypeScript. Each user supplies credentials for their own Shopify store.

<details>
<summary><strong>Prefer manual configuration?</strong></summary>

Generate a template without entering credentials or changing any client settings:

```bash
npx -y shopify-store-tools@latest config
npx -y shopify-store-tools@latest config --format vscode
npx -y shopify-store-tools@latest config --format codex
```

Replace the placeholders in the generated template locally. It launches the npm package through `npx`. Store credentials in private client configuration, outside the repository.

See [client setup](docs/clients.md) for configuration locations and formats.

</details>

<details>
<summary><strong>Shopify authentication and permissions</strong></summary>

Choose one authentication mode:

- **Dev Dashboard app:** `SHOPIFY_STORE_DOMAIN`, `SHOPIFY_CLIENT_ID`, and `SHOPIFY_CLIENT_SECRET`. Client credentials are for stores in your own Shopify organization.
- **Existing admin access token:** `SHOPIFY_STORE_DOMAIN` and `SHOPIFY_ADMIN_ACCESS_TOKEN`.

Grant only the scopes required for your intended operations. Customer data can require protected customer data approval. Orders older than 60 days normally require `read_all_orders`. Theme mutations can require Shopify's theme API exemption in addition to `write_themes`.

See [credentials and scopes](docs/credentials.md). `.env.example` documents variable names; the server reads process environment variables and does not automatically load `.env` files.

</details>

<details>
<summary><strong>Run from source instead</strong></summary>

```bash
git clone https://github.com/nazarii-nalyvaiko-bs/shopify-store-tools.git
cd shopify-store-tools
npm ci
npm run build
node dist/index.js init
```

For a built checkout, registration points at your local Node.js executable and this checkout's `dist/index.js`. Keep the directory in place.

</details>

## Connect the agent you use

The integration boundary is **standard MCP over stdio**, rather than an SDK for one vendor. Clients that can launch a local stdio MCP server can use the same Shopify tools. A client that only accepts remote HTTP servers needs a separate transport integration.

| Client | Setup |
| :--- | :--- |
| Claude Code | Wizard or `.mcp.json` |
| Cursor | Wizard or `.cursor/mcp.json` |
| GitHub Copilot in VS Code | Wizard or `.vscode/mcp.json` with a `servers` section |
| Codex CLI | Wizard or `config --format codex` |
| Gemini CLI, Claude Desktop, Windsurf | Wizard or client-specific MCP settings |
| Another local MCP client | `config` and the client's own MCP settings |

The [client guide](docs/clients.md) distinguishes protocol compatibility, generated configurations, and actual verification. It does not claim that every agent has been tested.

## Give your agent the workflow

The MCP server supplies tools. The included [Shopify Store Tools skill](skills/shopify-store-tools/SKILL.md) supplies the workflow: inspect existing state, choose a narrow operation, preserve unrelated data, and verify the result.

It uses the open [Agent Skills format](https://agentskills.io/specification), with a normal `SKILL.md` and task-specific references. Install the **whole** `skills/shopify-store-tools` folder in the skill directory supported by your agent. Skill discovery and installation locations are client-specific. For a client without native skills, attach the skill and its referenced documents as instructions; the MCP tools work independently.

The skill handles catalog and media tasks, theme and navigation changes, orders, customer history, discounts, and reports. It introduces no tool allowlist or vendor-specific namespace.

## Changes with clear boundaries

- **One process, one store.** Use separate MCP entries for separate stores.
- **Draft themes first.** Live theme edits and publication require explicit confirmation and a fresh check of the active theme.
- **Visible partial results.** Media processing, cancellation jobs, and interrupted pagination are reported as such.
- **Scoped operations.** Each tool has a typed input; there is no unrestricted API execution tool.

Read the [architecture notes](docs/architecture.md) for ownership, concurrency limits, and verification boundaries.

## Development

```bash
npm ci
npm test
npm audit --omit=dev
npm pack --dry-run
```

Tests exercise Shopify logic against mocked API responses, MCP discovery, configuration output, and CLI failures. These checks do not establish live-store operation or end-to-end execution inside every agent.

## License

[ISC](LICENSE)