MCP Medusa

Medusa.js MCP服务器

全面 模型上下文协议（MCP）服务器 为提供自动化API工具 美杜莎电子商务后端运营该服务器通过兼容MCP的工具公开了Medusa管理员API的所有主要功能，用于Claude Desktop等人工智能助手。

🏪 关于Medusa.js

Medusa.js 是一个为开发人员构建的现代开源电子商务平台。它提供了一个无头商务后端，具有强大的管理API，用于管理产品、订单、客户和电子商务运营的各个方面。

🚀 特性

完成管理API覆盖范围

此MCP服务器提供 14个综合管理工具 涵盖所有主要的Medusa.js操作：

• 🛍️ 产品管理 -产品、变体、类别、标签、类型
• 📦 订单管理 -列出、获取、取消、完成、存档、转移、履行
• 📋 草拟订单 -具有行项目管理的购物车功能
• 👥 客户管理 -客户CRUD、地址、客户组
• 📊 收集管理 -集合CRUD，产品关联
• 📈 库存管理 -库存物品、库存位置、级别、预订
• 🌍 地区和运输 -地区、运输选项、配置文件、履行
• 💰 定价和促销 -价目表、促销、活动
• 💳 付款和退款 -收款、收款、退款
• 🔄 退换货 -退货、换货、索赔、订单编辑
• 🎁 礼品卡 -礼品卡操作和余额管理
• 📈 税务管理 -税率和税区
• 📺 销售渠道 -渠道运营和产品关联
• 👤 用户和身份验证 -用户管理、邀请、API密钥

关键能力

• ✅ 200多项API操作 跨所有Medusa管理端点
• ✅ 完整的CRUD操作 所有主要资源
• ✅ 先进的电子商务运营 （履行、订单编辑、促销）
• ✅ MCP兼容 实现无缝的AI助手集成
• ✅ 无需安装 -直接使用npx运行
• ✅ 全面的错误处理 和验证

🚦 快速开始

先决条件

• 运行Medusa.js后端服务器
• Medusa管理员API密钥

使用模式

MCP美杜莎支持 三种使用模式:

______________________________________________________________________

选项1：本地模式（STDIO）

最适合： 使用Claude Desktop、Windsurf、Cursor或其他MCP兼容IDE的个人开发人员。

通过npx在本地直接集成运行，无需部署服务器。

Claude桌面配置

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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"
      }
    }
  }
}

风帆配置

位置: ~/.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"
      }
    }
  }
}

______________________________________________________________________

选项2：远程模式（HTTP）-适用于Web应用程序

最适合： 与LLM集成的Web应用程序需要以编程方式访问Medusa操作。

部署到数字海洋应用平台，然后通过HTTP从您的web应用程序连接。

第一步：部署到数字海洋

# 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

步骤2：在DO仪表板中配置机密

首选 应用程序>mcp-medusa>设置>应用程序级环境变量 并添加：

步骤3：从Web应用程序连接

初始化会话：

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' }
    }
  })
});

列出可用工具：

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);

执行工具：

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端点引用

______________________________________________________________________

选项3：通过mcp-Remote进行远程（IDE到远程服务器）

最适合： 多个开发人员需要共享单个MCP服务器部署的团队，或者当您希望IDE访问远程Medusa实例时。

这使用了 mcp-remote 使用Streamable HTTP传输将基于STDIO的本地IDE桥接到远程HTTP服务器的包。

先决条件

1. MCP Medusa部署到数字海洋（见选项2）
2. MCP_AUTH_TOKEN 在部署中配置

Claude桌面配置

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"
      }
    }
  }
}

风帆配置

位置: ~/.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"
      }
    }
  }
}

光标配置

位置：光标设置>MCP服务器

{
  "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"
      }
    }
  }
}

mcp-remote的工作原理

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

1. 您的IDE生成 mcp-remote 作为本地进程
2. mcp-remote 通过Streamable HTTP连接到远程MCP服务器
3. IDE中的命令被转发到远程服务器
4. 响应通过网桥返回

mcp遥控器的优点

• 共享部署：多个团队成员使用同一个MCP服务器
• 集中式美杜莎访问：与您的Medusa后端建立一个安全连接
• 没有本地凭据：API密钥留在服务器上，仅本地需要身份验证令牌
• 适用于任何兼容MCP的IDE：克劳德桌面、风帆、光标等。

______________________________________________________________________

配置参考

获取Medusa API密钥

1. 访问您的Medusa管理员仪表板
2. 首选 设置 → API密钥
3. 创建具有管理员权限的新API密钥
4. 复制密钥并将其添加到您的配置中

验证安装

配置Claude Desktop后：

1. 完全重新启动克劳德桌面
2. 在聊天界面中查找MCP服务器指示灯（锤子图标）
3. 服务器连接时应显示绿色状态指示灯

🔧 工具示例

订单管理

// 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"
}

产品管理

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

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

客户管理

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

// Create customer
{
  "action": "create",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe"
}

📊 可用工具参考

🧪 与Claude一起测试

配置后，请尝试与Claude一起执行以下提示：

1. *“显示我的美杜莎商店的最新订单”*
2. *“创建一个名为“测试产品”的新产品，价格为29.99美元”*
3. *“列出最近的客户及其详细信息”*
4. *“检查所有产品的库存水平”*
5. *创建一个名为“VIP”的新客户群*

🔒 安全最佳实践

• 永远不要共享您的API密钥 -确保它们的安全和私密性
• 在生产环境中使用HTTPS -配置 MEDUSA_BASE_URL 使用HTTPS
• 定期旋转API键 -定期生成新的管理员API密钥
• 限制API密钥权限 -使用具有适当角色限制的管理员用户

______________________________________________________________________

发展与贡献

以下部分适用于希望为此项目做出贡献或在本地运行以进行开发的开发人员。

📥 地方发展设置

1.克隆存储库

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

2.安装依赖项

npm install

3.配置环境变量

cp env.example .env

更新 .env 使用您的Medusa配置：

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

🏃‍♂️ 本地运行

STDIO模式（用于克劳德桌面测试）：

npm run dev
# or
node mcpServer.js

HTTP模式（适用于web应用程序和mcp-remote）：

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

Vercel当地发展：

npm run dev:vercel

🛠️ CLI命令

列出可用工具：

npm run list-tools

测试美杜莎连接：

node test-medusa-tools.js

测试MCP工具：

node test-mcp-tools.js

🧪 MCP检验员测试

# 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 -t medusa-mcp .

使用环境文件运行：

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

☁️ Vercel部署

# Deploy to production
vercel --prod

在Vercel仪表板中设置环境变量：

• MEDUSA_BASE_URL
• MEDUSA_API_KEY

📂 项目结构

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

🛠️ 添加新工具

1. 在中创建新工具文件 tools/medusa-admin-api/
2. 遵循现有的工具模式：

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

1. 将刀具路径添加到 tools/paths.js
2. 测试用 npm run list-tools

🤝 贡献

1. 复刻仓库
2. 创建要素分支： git checkout -b feature/new-tool
3. 实施您的更改
4. 彻底测试： npm run list-tools && node test-medusa-tools.js
5. 提交拉取请求

📚 资源

• Medusa.js文档 -美杜莎官方文件
• 美杜莎管理API参考 -完整的API参考
• 模型上下文协议 -MCP规范
• 克劳德桌面版 -支持MCP的AI助手

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

💬 支持

• 问题:
• 文档：有关API的详细信息，请查看Medusa.js文档
• 社区：加入Medusa Discord社区以获得一般支持

______________________________________________________________________

为Medusa.js生态系统构建 🏪 由模型上下文协议提供支持 🤖