Home

Vex

Vex — the Vendure Admin GraphQL executor. One tool, two ways to use it:

• a CLI you run in your terminal to manage products, customers, orders, and more, and
• an MCP server you connect to Claude, so Claude can do all of that for you through natural language.

It wraps the Vendure Admin GraphQL API and is schema-aware, so it works with core Vendure and any custom plugins that extend the Admin API.

---

Choose your path

If you…	Start here
🆕 are new to Claude and want Claude to manage Vendure for you	Claude Code Setup
🧰 want to understand the tools Claude uses under the hood	MCP Tools Guide
⌨️ prefer working in the terminal	CLI Usage

---

Install

npm install -g @spaceparrots/vex

This puts the vex command on your PATH.

You'll need:

• Node 20.19+ or 22.12+ — check with node --version.
• A Vendure 3.6+ store, running and reachable. Vex authenticates with an API key sent in the vendure-api-key header (the API-key auth method introduced in Vendure 3.6). You create that key once in your Vendure dashboard — Claude Code Setup → Step 1 walks you through it, including which permissions to grant.

Prefer no global install? Run it ad-hoc with npx -y @spaceparrots/vex — the MCP client can invoke that directly, so there's nothing to install first.

🔒 Vex can write to your store. It has exactly the powers your API key has — so scope the key, and point Claude at a dev store before a production one. See Safety.

---

Where things live

All of Vex's state lives under ~/.vendure-vex/ (%USERPROFILE%\.vendure-vex\ on Windows):

Path	What's there
config.json	Your environments (url, apiKey, optional schemaSource), the active one, and any project-directory links (vex env link)
schemas/<env>.graphql	Cached GraphQL schema per environment
fragments/<env>/<Name>.graphql	Saved reusable field selections
operations/<env>/<Name>.json	Saved, replayable queries/mutations

Your API key is stored in plaintext in config.json — treat that file like an SSH private key. You can manage all of this from the CLI or, when connected to Claude, via the MCP tools.

---

What's new

• Asset uploads — vex asset upload (and the vex_assets MCP tool) send local files to Vendure. For custom plugin mutations with their own file variables, vex mutate --file / vex_mutate's files param is the raw escape hatch.
• Project-linked environments — vex env link ties a directory to an environment so Vex auto-selects it there, no VEX_ENV or manual switching needed.
• One-command Claude setup — vex mcp install writes .mcp.json, lets you pick lean or full tools, and links the project to an environment for you.
• vex status — a one-glance health panel: version, active environment (and why it was picked), endpoint reachability + latency, masked API key, schema cache age, and config path.
• Permission-aware errors — FORBIDDEN/UNAUTHORIZED failures now name the denied operation and suggest likely Permission values; browse the full list with vex schema permissions.
• CLI shortcuts — vex products, vex customers, vex use <env>, and friends jump straight to the common subcommand, with typo suggestions when you mistype a command.

See CLI Usage and MCP Tools Guide for the full details.