npm package: @spaceparrots/vex
Description: CLI tool and MCP server for Vendure Admin API
Latest version: 0.0.3

# Vex
![](https://img.shields.io/badge/Node.js-20%2B-brightgreen?style=flat-square) [![npm]](https://www.npmjs.com/package/@spaceparrots/vex)

[npm]: https://img.shields.io/npm/v/%40spaceparrots%2Fvex.svg?style=flat-square

Your **v**endure admin-api graphql query **ex**ecutor. CLI tool and MCP server for the Vendure Admin GraphQL API.

![vex-mascot-banner](https://github.com/user-attachments/assets/52237673-4c6b-4e12-966a-8ab942e95744)

Use `vex` from your terminal to manage products, customers, and orders — or connect it as an MCP server so Claude can do it for you.

## Features

- **Environment management** — add, switch, and configure multiple Vendure instances
- **Typed resource commands** — CRUD operations for customers, products, and orders out of the box
- **Raw GraphQL** — run any query or mutation directly from the terminal
- **Schema caching** — fetch and cache your Vendure schema for offline reference
- **MCP server** — expose all commands as tools so Claude can chain them via natural language

## Installation

```bash
npm install -g @spaceparrots/vex
```

This puts the `vex` command on your PATH.

## Requirements

**Vendure 3.6+** is required. Vex uses the [API key authentication](https://docs.vendure.io/current/core/developer-guide/api-keys) method introduced in Vendure 3.6.

To set up your Vendure instance:

1. Enable API key auth in your Vendure config:
   ```ts
   authOptions: {
       tokenMethod: ['cookie', 'bearer', 'api-key'],
   }
   ```
2. Go to **Settings > API Keys** in the Vendure dashboard
3. Create a new key, assign the roles/permissions it needs, and copy the key (it's shown only once)

The key is sent via the `vendure-api-key` header on every request.

## Quick start

```bash
# Add an environment
vex env add dev --url http://localhost:3000/admin-api --api-key sk-123456

# List products
vex product list

# Create a customer
vex customer create --email john@example.com --first-name John --last-name Doe

# Run any GraphQL query
vex query '{ products { items { id name } totalItems } }'

# Fetch and cache the schema
vex schema fetch
```

## CLI reference

### Environment management

```bash
vex env add <name> --url <url> --api-key <key>   # Add environment
                   [--schema-type endpoint|file]   # Schema source type
                   [--schema-value <value>]         # Introspection URL or file path
                   [--fetch-schema]                 # Fetch schema immediately
vex env list                                       # List all environments
vex env switch <name>                              # Switch active environment
vex env set <name> [--url <url>] [--api-key <key>] # Update environment fields
vex env remove <name>                              # Remove environment
vex env show [name]                                # Show environment details
```

### Schema

```bash
vex schema fetch [--env <name>]     # Fetch and cache GraphQL schema
```

### Generic GraphQL

```bash
vex query '<graphql>' [--variables '<json>']    # Run any query
vex mutate '<graphql>' [--variables '<json>']   # Run any mutation
```

### Customers, Products & Orders

Each resource supports `list`, `get`, `create`, `update`, and `delete` plus resource-specific actions (e.g. `customer add-note`, `product add-variants`, `order transition`). Run `vex <resource> --help` for full options.

## MCP setup (Claude Code)

Add to your project's `.mcp.json` or global `~/.claude.json`:

```json
{
  "mcpServers": {
    "vex": {
      "command": "npx",
      "args": ["-y", "@spaceparrots/vex"]
    }
  }
}
```
> Windows might require to run it via `cmd /c "npx -y @spaceparrots/vex"`

Running `vex` with no arguments starts the MCP server on stdio — this is what MCP clients expect.

Once connected, ask Claude:

> Add my Vendure dev server at http://localhost:3000/admin-api with API key sk-1234

Then you can use natural language:

> Create me a dummy order for product "shoes"

Claude will check if the product exists, create it if needed, find or create a customer, create a draft order, and add items — all by chaining the MCP tools automatically.

### Available MCP tools

When used as an MCP server, vex exposes 23 tools:

| Tool | Description |
|------|-------------|
| `vendure_setup` | Add, remove, list, switch, set, or show environments |
| `vendure_refetch_schema` | Re-fetch and cache the GraphQL schema |
| `vendure_query` | Execute any GraphQL query |
| `vendure_mutate` | Execute any GraphQL mutation |
| `vendure_get_customers` | List customers with filters |
| `vendure_get_customer` | Get customer by ID with addresses and orders |
| `vendure_create_customer` | Create a customer |
| `vendure_update_customer` | Update a customer |
| `vendure_delete_customer` | Delete a customer |
| `vendure_add_customer_note` | Add a note to a customer |
| `vendure_get_products` | List products with filters |
| `vendure_get_product` | Get product by ID with variants and facets |
| `vendure_create_product` | Create a product |
| `vendure_update_product` | Update a product |
| `vendure_delete_product` | Delete a product |
| `vendure_create_product_variants` | Create variants for a product |
| `vendure_get_orders` | List orders with filters |
| `vendure_get_order` | Get order by ID with lines and payments |
| `vendure_create_draft_order` | Create a draft order |
| `vendure_add_item_to_draft_order` | Add item to a draft order |
| `vendure_set_customer_for_draft_order` | Assign customer to a draft order |
| `vendure_transition_order` | Transition order state |
| `vendure_cancel_order` | Cancel an order |

## Configuration

Environments are stored at `~/.vendure-vex/config.json`. Each has:

- **url** — Vendure Admin API endpoint
- **apiKey** — sent as the `vendure-api-key` header
- **schemaSource** (optional) — `"endpoint"` to introspect, or `"file"` to load local SDL

Cached schemas live at `~/.vendure-vex/schemas/`.

## Development

```bash
npm install
npm run build        # Compile to dist/
npm run dev          # Run with tsx (no build)
npm run typecheck    # Type check only
```

## License

MIT