Vendure MCP Server

A standalone Model Context Protocol (MCP) server for Vendure CLI orchestration. This independent package allows external clients to interact with Vendure CLI commands in a programmatic way, enabling automation and integration with various MCP clients like Cursor.

Features

• CLI Integration: Direct access to Vendure CLI add and migrate commands.
• Project Analysis: Analyze project structure, list plugins, entities, and services.
• Environment Check: Verify Vendure installation and dependencies.
• Dual Transport: Support for both STDIO and HTTP transport protocols.
• Real-time: Works with any Vendure project without modification.

Installation

From npm (Recommended)

Install globally for easy access

npm install -g @vendure/mcp-server

Or install locally in your project

npm install @vendure/mcp-server

From Source

git clone https://github.com/vendure-ecommerce/mcp.git
cd vendure-mcp
npm install
npm run build

Usage and Configuration

This guide provides instructions for both end-users (using the published npm package) and developers (working from the source code).

For End-Users (Published Package)

If you have installed the server from npm, you can use npx to run it without requiring a global installation.

MCP Client Configuration

Add the following to your MCP client's configuration file:

If you have installed the package globally (npm install -g @vendure/mcp-server), you can add it directly in your mcp.json:

{
  "mcpServers": {
    "vendure": {
      "command": "npx",
      "args": ["@vendure/mcp-server"]
    }
  }
}

This command will automatically download and run the latest version of the server.

Starting the HTTP Server

If you have installed the package locally, you would have to run it on a server:

vendure-mcp --transport http --port 8000

Your mcp.json should then look like this:

{
  "mcpServers": {
    "vendure": {
      "command": "http://localhost:8000"
    }
  }
}

For Developers (Local Source)

When developing the server, you should run it directly from the source code to ensure you are using your latest changes.

MCP Client Configuration (Development)

To connect your MCP client to the local development server, configure it to use the npm run dev script. This provides live reloading for a smoother development experience.

{
  "mcpServers": {
    "vendure-dev": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/your/vendure-mcp/project"
    }
  }
}

Note: Ensure the cwd (current working directory) points to the root of this project.

Starting the Dev Server Manually

You can also run the development server directly from your terminal:

# Start STDIO dev server with live-reloading
npm run dev

# Start HTTP dev server with live-reloading
npm run dev:http

Available Tools

1. vendure_add

2. vendure_migrate

3. list_plugins

4. analyze_project_structure

5. check_vendure_installation

Dynamic CLI Integration

The server dynamically generates MCP tools from Vendure CLI command definitions. This ensures:

• Single Source of Truth: CLI changes automatically reflect in MCP tools.
• Type Safety: Full TypeScript integration with proper parameter validation.
• Future-proof: New CLI commands and options become available automatically.
• No Hallucinations: The code generated by the tools, specifically the cli tools will always be correct.

Development

Building from Source

git clone https://github.com/vendure-ecommerce/mcp.git
cd vendure-mcp
npm install
npm run build

Development Mode

STDIO mode

npm run dev

HTTP mode

npm run dev:http

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Error Handling

Comprehensive error handling includes:

• Project path validation
• Vendure CLI availability checks
• Parameter validation with detailed messages
• CLI execution error forwarding
• File system operation safety

Security

• Path validation: Prevents directory traversal attacks
• Input sanitization: All parameters validated against schemas
• Isolated execution: Commands run in specified project directories only
• No elevated privileges: Runs with standard user permissions

Contributing

Follow our contributing guide in our main repository.

Links

• Vendure Core
• Vendure Documentation
• MCP Specification
• GitHub Repository