npm package: @iflow-mcp/vendure-ecommerce-mcp
Description: The official Vendure MCP server
Latest version: 1.0.4-alpha

<p align="center">
  <a href="https://vendure.io">
    <img alt="Vendure logo" height="60" width="auto" src="https://a.storyblok.com/f/192301/252x200/c6608214a9/brand-icon-primary.svg">
  </a>
</p>

<h1 align="center">
  Vendure MCP Server
</h1>
<p align="center">
    A standalone Model Context Protocol (MCP) server for Vendure CLI orchestration. This package runs on a per-project basis, allowing external clients like Cursor to interact with your local Vendure project's CLI commands in a programmatic and context-aware way.

</p>

<p align="center">
  <a href="https://vendure.io/community">
    <img src="https://img.shields.io/badge/join-our%20discord-7289DA.svg" alt="Join our Discord" />
  </a>
  <a href="https://twitter.com/intent/follow?screen_name=vendure_io">
    <img src="https://img.shields.io/twitter/follow/vendure_io" alt="Follow @vendure_io" />
  </a>
</p>

## Features

- **Project Integration**: Operates directly within your Vendure project, providing context-aware tooling.
- **CLI Integration**: Direct access to Vendure CLI `add` and `migrate` commands.
- **Project Analysis**: Analyze project structure, list plugins, entities, and services.
- **Dual Transport Support**: Connect via standard I/O (STDIO) for local clients like Cursor or via HTTP for networked clients.
- **Environment Check**: Verify Vendure installation and dependencies within the project.
- **Access to Docs**: The MCP can fetch the official Vendure docs to use as context whenever it needs to.
- **Real-time**: Works with any local Vendure project without modification.

## Dynamic CLI Integration

The server dynamically generates MCP tools from your project's installed Vendure CLI command definitions. This ensures:

- **Single Source of Truth**: CLI changes automatically reflect in MCP tools.
- **Future-proof**: New CLI commands and options become available automatically.
- **No Hallucinations**: The code generated by the tools will always be correct, as it's based on the actual CLI definitions in your project.

## Installation and Setup Workflow

> [!WARNING]
> To use the CLI command orchestration capabilities of the MCP. The target project should be running a version of the `@vendure/cli` package that is > 3.4.0 or later. Currently, this would be in our minor branch.
>
> To change the version of your package, open the `package.json` of your project and change the "@vendure/cli" version to "minor", then delete your `package-lock.json` file and `node_modules` folder and run `npm install`.

The server is designed to be installed and run directly from your Vendure project. This ensures it always has access to the correct dependencies and project context.

Configure Your MCP Client (e.g., Cursor)

Create or update the `mcp.json` file used by your MCP client. This file is typically located at `.cursor/mcp.json` inside your project's root folder.

Below are configurations for both STDIO and HTTP connections.

> [!IMPORTANT]
> You must restart your MCP client, e.g., Cursor IDE or Claude Code, to apply the changes.

### Option 1: STDIO Connection (Recommended for Local Clients)

This is the simplest and most direct way to connect.

```json
{
    "mcpServers": {
        "vendure-local-mcp": {
            "command": "npx",
            "args": ["@vendure/mcp-server@latest", "--projectPath", "/path/to/your/vendure-project"]
        }
    }
}
```

> [!IMPORTANT]
> You must replace `/path/to/your/vendure-project` with the **absolute path** to your Vendure project's root directory. The same path as your `vendure-config.ts`.

### Option 2: HTTP Connection

If your client does not support STDIO or you need to connect over a network, you can run the server in HTTP mode.

First, start the server from your terminal in your **Vendure project's root directory**:

```bash
npx @vendure/mcp-server@latest --transport http --projectPath .
```

This will start the server on the default port (8000), you can explicitly define the port by using the `--port <0000>` flag.

Then, configure your `mcp.json` to connect to the running server's URL:

```json
{
    "mcpServers": {
        "vendure": {
            "url": "http://localhost:8000/mcp"
        }
    }
}
```

### Option 3: Docker

This will start a Docker container and the server will run through in stdio mode. Refer to the [Docker Guide](https://github.com/vendure-ecommerce/mcp/blob/master/README-Docker.md) for more information about running with Docker.

```json
{
    "mcpServers": {
        "vendure-mcp-docker": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "--env",
                "PROJECT_PATH=/workspace",
                "--volume",
                "/absolute/path/to-your-vendure-project:/workspace",
                "vendure/mcp:latest",
                "--projectPath",
                "/workspace"
            ]
        }
    }
}
```

> [!IMPORTANT]
> You must replace `/path/to/your/vendure-project` with the **absolute path** to your Vendure project's root directory. The same path as your `vendure-config.ts`.

## Development

If you are contributing to the Vendure MCP server itself, you'll want to run it from the source code.

### Build from Source

```bash
git clone https://github.com/vendure-ecommerce/mcp.git
cd vendure-mcp-server # Or the correct directory name
npm install
npm run build
```

### Development Mode

To connect an MCP client to your local development server, use the `npm run dev` script and point it to a test Vendure project. You can run it in either STDIO or HTTP mode.

- **STDIO Mode**: `npm run dev -- --projectPath /path/to/your/test-vendure-project`
- **HTTP Mode**: `npm run dev:http -- --projectPath /path/to/your/test-vendure-project`

Configure your `mcp.json` as described in the setup section to connect to your development server. The `--` is required to pass arguments to the npm script correctly.

## Trouble-shooting and issue reporting

If you run into problems while using/running the MCP, we would appreciate any issue with information that would help us reproduce your issue.

> [!TIP]
> you can provide us with **MCP Logs** created by your MCP-Client.
> In Cursor, you could find them by looking for `Developer: Open Log File...` > `MCP Logs` in your command palette (Shift+Cmd/Ctrl/Super+P) by default.

## Links

- [Vendure Core](https://github.com/vendure-ecommerce/vendure)
- [Vendure Documentation](https://www.vendure.io/docs/)
- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [GitHub Repository](https://github.com/vendure-ecommerce/mcp)