Medusa.js MCP Server

A comprehensive Model Context Protocol (MCP) server that provides automated API tools for Medusa e-commerce backend operations. This server exposes all major Medusa admin API functionality through MCP-compatible tools for use with AI assistants like Claude Desktop.

🏪 About Medusa.js

Medusa.js is a modern, open-source e-commerce platform built for developers. It provides a headless commerce backend with powerful admin APIs for managing products, orders, customers, and all aspects of e-commerce operations.

🚀 Features

Complete Admin API Coverage

This MCP server provides 14 comprehensive admin tools covering all major Medusa.js operations:

• 🛍️ Products Management - Products, variants, categories, tags, types
• 📦 Orders Management - List, get, cancel, complete, archive, transfer, fulfillment
• 📋 Draft Orders - Cart-like functionality with line item management
• 👥 Customers Management - Customer CRUD, addresses, customer groups
• 📊 Collections Management - Collections CRUD, product associations
• 📈 Inventory Management - Inventory items, stock locations, levels, reservations
• 🌍 Regions & Shipping - Regions, shipping options, profiles, fulfillment
• 💰 Pricing & Promotions - Price lists, promotions, campaigns
• 💳 Payments & Refunds - Payment collections, captures, refunds
• 🔄 Returns & Exchanges - Returns, swaps, claims, order edits
• 🎁 Gift Cards - Gift card operations and balance management
• 📈 Tax Management - Tax rates and tax regions
• 📺 Sales Channels - Channel operations and product associations
• 👤 Users & Auth - User management, invites, API keys

Key Capabilities

• ✅ 200+ API actions across all Medusa admin endpoints
• ✅ Full CRUD operations for all major resources
• ✅ Advanced e-commerce operations (fulfillment, order edits, promotions)
• ✅ MCP-compatible for seamless AI assistant integration
• ✅ Zero installation required - run directly with npx
• ✅ Comprehensive error handling and validation

🚦 Quick Start

Prerequisites

• Node.js v18+ (v20+ recommended)
• Running Medusa.js backend server
• Medusa admin API key

Usage Modes

MCP Medusa supports three usage modes:

| Mode | Transport | Use Case | Best For | |------|-----------|----------|----------| | Local | STDIO | Direct IDE integration (npx) | Individual developers | | Remote HTTP | Streamable HTTP | Web apps with LLM integration | Production web apps | | Remote via mcp-remote | STDIO → HTTP bridge | IDEs connecting to remote server | Teams sharing one deployment |

Option 1: Local Mode (STDIO)

Best for: Individual developers using Claude Desktop, Windsurf, Cursor, or other MCP-compatible IDEs.

Direct integration running locally via npx - no server deployment needed.

Claude Desktop Configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "medusa-admin": {
      "command": "npx",
      "args": ["-y", "mcp-medusa"],
      "env": {
        "MEDUSA_BASE_URL": "http://localhost:9000",
        "MEDUSA_API_KEY": "your_admin_api_key"
      }
    }
  }
}

Windsurf Configuration

Location: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "medusa-admin": {
      "command": "npx",
      "args": ["-y", "mcp-medusa"],
      "env": {
        "MEDUSA_BASE_URL": "http://localhost:9000",
        "MEDUSA_API_KEY": "your_admin_api_key"
      }
    }
  }
}

Option 2: Remote Mode (HTTP) - For Web Apps

Best for: Web applications integrated with LLMs that need to access Medusa operations programmatically.

Deploy to Digital Ocean App Platform, then connect from your web application via HTTP.

Step 1: Deploy to Digital Ocean

# Install doctl CLI
brew install doctl  # macOS
snap install doctl  # Linux

# Authenticate
doctl auth init

# Create app (requires GitHub connection in DO Dashboard first)
doctl apps create --spec deployment/digitalocean/app.yaml

Step 2: Configure Secrets in DO Dashboard

Go to Apps > mcp-medusa > Settings > App-Level Environment Variables and add:

| Variable | Type | Description | |----------|------|-------------| | MEDUSA_BASE_URL | Secret | Your Medusa backend URL (e.g., https://api.mystore.com) | | MEDUSA_API_KEY | Secret | Medusa admin API key | | MCP_AUTH_TOKEN | Secret | Generate with openssl rand -base64 32 |

Step 3: Connect from Your Web App

Initialize session:

const MCP_URL = 'https://your-app.ondigitalocean.app/mcp';
const AUTH_TOKEN = 'your_mcp_auth_token';

// Initialize MCP session
const initResponse = await fetch(MCP_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${AUTH_TOKEN}`
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'initialize',
    params: {
      clientInfo: { name: 'my-web-app', version: '1.0.0' }
    }
  })
});

List available tools:

const toolsResponse = await fetch(MCP_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${AUTH_TOKEN}`
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 2,
    method: 'tools/list'
  })
});

const { result } = await toolsResponse.json();
console.log('Available tools:', result.tools);

Execute a tool:

const ordersResponse = await fetch(MCP_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${AUTH_TOKEN}`
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 3,
    method: 'tools/call',
    params: {
      name: 'manage_medusa_admin_orders',
      arguments: {
        action: 'list',
        limit: 10
      }
    }
  })
});

const { result } = await ordersResponse.json();
console.log('Orders:', JSON.parse(result.content[0].text));

HTTP Endpoints Reference

| Endpoint | Method | Auth | Description | |----------|--------|------|-------------| | /health | GET | No | Liveness check | | /ready | GET | No | Readiness check (shows tools count) | | /mcp | POST | Bearer | Main MCP JSON-RPC endpoint (Streamable HTTP) |

Option 3: Remote via mcp-remote (IDEs to Remote Server)

Best for: Teams where multiple developers need to share a single MCP server deployment, or when you want IDE access to a remote Medusa instance.

This uses the mcp-remote package to bridge local STDIO-based IDEs to a remote HTTP server using Streamable HTTP transport.

Prerequisites

1. MCP Medusa deployed to Digital Ocean (see Option 2)
2. MCP_AUTH_TOKEN configured in the deployment

Claude Desktop Configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "medusa-remote": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-app.ondigitalocean.app/mcp",
        "--header", "Authorization:Bearer ${MCP_AUTH_TOKEN}"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your_secure_token_here"
      }
    }
  }
}

Windsurf Configuration

Location: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "medusa-remote": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-app.ondigitalocean.app/mcp",
        "--header", "Authorization:Bearer ${MCP_AUTH_TOKEN}"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your_secure_token_here"
      }
    }
  }
}

Cursor Configuration

Location: Cursor Settings > MCP Servers

{
  "mcpServers": {
    "medusa-remote": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-app.ondigitalocean.app/mcp",
        "--header", "Authorization:Bearer ${MCP_AUTH_TOKEN}"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your_secure_token_here"
      }
    }
  }
}

How mcp-remote Works

┌─────────────────┐     STDIO      ┌─────────────────┐     HTTPS     ┌─────────────────┐
│  Claude Desktop │ ◄────────────► │   mcp-remote    │ ◄───────────► │  MCP Medusa     │
│  Windsurf       │                │   (npx bridge)  │               │  (Digital Ocean)│
│  Cursor         │                └─────────────────┘               └────────┬────────┘
└─────────────────┘                                                           │
                                                                     ┌────────▼────────┐
                                                                     │  Medusa Backend │
                                                                     └─────────────────┘

1. Your IDE spawns mcp-remote as a local process
2. mcp-remote connects to the remote MCP server via Streamable HTTP
3. Commands from the IDE are forwarded to the remote server
4. Responses are returned back through the bridge

Advantages of mcp-remote

• Shared deployment: Multiple team members use the same MCP server
• Centralized Medusa access: One secure connection to your Medusa backend
• No local credentials: API keys stay on the server, only auth token needed locally
• Works with any MCP-compatible IDE: Claude Desktop, Windsurf, Cursor, etc.

Configuration Reference

| Variable | Required | Mode | Description | Example | |----------|----------|------|-------------|---------| | MEDUSA_BASE_URL | Yes | All | Your Medusa backend URL | http://localhost:9000 | | MEDUSA_API_KEY | Yes | All | Admin API key or JWT token | sk_admin_... | | MCP_AUTH_TOKEN | Remote only | HTTP | Token for client authentication | openssl rand -base64 32 |

Getting Your Medusa API Key

1. Access your Medusa Admin dashboard
2. Go to Settings → API Keys
3. Create a new API key with admin permissions
4. Copy the key and add it to your configuration

Verify Installation

After configuring Claude Desktop:

1. Restart Claude Desktop completely
2. Look for the MCP server indicator (hammer icon) in the chat interface
3. The server should show a green status indicator when connected

🔧 Tool Examples

Orders Management

// List orders with filtering
{
  "action": "list",
  "limit": 10,
  "status": "pending"
}

// Get specific order
{
  "action": "get",
  "id": "order_01234567890"
}

// Complete an order
{
  "action": "complete",
  "id": "order_01234567890"
}

Products Management

// List products
{
  "action": "list",
  "limit": 20,
  "status": "published"
}

// Create new product
{
  "action": "create",
  "title": "New Product",
  "description": "Product description",
  "handle": "new-product"
}

Customers Management

// List customers
{
  "action": "list",
  "limit": 50
}

// Create customer
{
  "action": "create",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe"
}

📊 Available Tools Reference

| Tool | Description | Key Actions | |------|-------------|-------------| | manage_medusa_admin_orders | Order management & fulfillment | list, get, cancel, complete, archive, transfer | | manage_medusa_admin_draft_orders | Cart-like draft order operations | create, list, get, delete, convert_to_order | | manage_medusa_admin_products | Product & variant management | list, get, create, update, delete, list_variants | | manage_medusa_admin_customers | Customer & group management | list, get, create, update, delete, list_groups | | manage_medusa_admin_collections | Collection management | list, get, create, update, delete, add_products | | manage_medusa_admin_inventory | Inventory & stock management | list_items, list_locations, list_levels, create_reservation | | manage_medusa_admin_regions | Regions & shipping | list_regions, list_shipping_options, create_region | | manage_medusa_admin_pricing | Pricing & promotions | list_price_lists, list_promotions, list_campaigns | | manage_medusa_admin_payments | Payment operations | list_payments, capture_payment, refund_payment | | manage_medusa_admin_returns | Returns & exchanges | list_returns, list_exchanges, list_claims | | manage_medusa_admin_gift_cards | Gift card management | list, get, create, update, delete | | manage_medusa_admin_taxes | Tax management | list_tax_rates, list_tax_regions, create_tax_rate | | manage_medusa_admin_sales_channels | Sales channel management | list, get, create, add_products | | manage_medusa_admin_users | User & auth management | list_users, list_invites, list_api_keys |

🧪 Testing with Claude

Once configured, try these prompts with Claude:

1. "Show me the latest orders from my Medusa store"
2. "Create a new product called 'Test Product' with a price of $29.99"
3. "List the most recent customers and their details"
4. "Check the inventory levels for all products"
5. "Create a new customer group called 'VIP'"

🔒 Security Best Practices

• Never share your API keys - Keep them secure and private
• Use HTTPS in production - Configure MEDUSA_BASE_URL with HTTPS
• Rotate API keys regularly - Generate new admin API keys periodically
• Limit API key permissions - Use admin users with appropriate role restrictions

Development & Contributing

The following sections are for developers who want to contribute to this project or run it locally for development purposes.

📥 Local Development Setup

1. Clone the repository

git clone https://github.com/minimalart/mcp-medusa.git
cd mcp-medusa

2. Install dependencies

npm install

3. Configure environment variables

cp env.example .env

Update .env with your Medusa configuration:

MEDUSA_BASE_URL=http://localhost:9000
MEDUSA_API_KEY=your_admin_api_key_or_jwt_token

🏃‍♂️ Running Locally

STDIO Mode (for Claude Desktop testing):

npm run dev
# or
node mcpServer.js

HTTP Mode (for web apps and mcp-remote):

npm run dev:http
# or
node server/index.js

Vercel Local Development:

npm run dev:vercel

🛠️ CLI Commands

List available tools:

npm run list-tools

Test Medusa connectivity:

node test-medusa-tools.js

Test MCP tools:

node test-mcp-tools.js

🧪 Testing with MCP Inspector

# STDIO mode
npx @modelcontextprotocol/inspector@latest node mcpServer.js

# Vercel dev mode (requires Vercel dev running)
npx @modelcontextprotocol/inspector@latest http://localhost:3000/api/mcp

🐳 Docker

Build image:

docker build -t medusa-mcp .

Run with environment file:

docker run -i --rm --env-file=.env medusa-mcp

☁️ Vercel Deployment

# Deploy to production
vercel --prod

Set environment variables in Vercel dashboard:

• MEDUSA_BASE_URL
• MEDUSA_API_KEY

📂 Project Structure

mcp-medusa/
├── mcpServer.js              # STDIO transport (local IDEs)
├── server/
│   ├── index.js              # HTTP transport (remote/web)
│   ├── transports/
│   │   └── streamable-http.js # Streamable HTTP implementation
│   └── middleware/
│       └── auth.js           # Bearer token authentication
├── lib/
│   ├── tools.js              # Tool discovery system
│   └── constants.js          # Shared configuration
├── tools/
│   └── medusa-admin-api/     # All Medusa admin tools
│       ├── medusa-admin-orders.js
│       ├── medusa-admin-products.js
│       ├── medusa-admin-customers.js
│       └── ...
├── deployment/
│   └── digitalocean/
│       └── app.yaml          # DO App Platform config
├── docs/
│   └── REMOTE-SETUP.md       # Remote deployment guide
├── index.js                  # CLI entry point
└── commands/tools.js         # CLI tool listing command

🛠️ Adding New Tools

1. Create new tool file in tools/medusa-admin-api/
2. Follow the existing tool pattern:

   export const apiTool = {
     definition: {
       name: 'your_tool_name',
       description: 'Tool description',
       parameters: { /* parameter schema */ }
     },
     function: yourToolFunction
   };

3. Add tool path to tools/paths.js
4. Test with npm run list-tools

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-tool
3. Implement your changes
4. Test thoroughly: npm run list-tools && node test-medusa-tools.js
5. Submit a pull request

📚 Resources

• Medusa.js Documentation - Official Medusa documentation
• Medusa Admin API Reference - Complete API reference
• Model Context Protocol - MCP specification
• Claude Desktop - AI assistant with MCP support

📄 License

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

💬 Support

• Issues: Open an issue on GitHub
• Documentation: Check the Medusa.js documentation for API details
• Community: Join the Medusa Discord community for general support

Built for the Medusa.js ecosystem 🏪 Powered by Model Context Protocol 🤖