MCP VTEX服务器
完成Claude Desktop和Cursor的VTEX API集成 -通过人工智能对话管理您的整个电子商务运营。使用自然语言控制目录、库存、定价、促销、订单和市场运营。
______________________________________________________________________
✨ 特性
📦 目录管理
- 产品：产品的完整CRUD操作
- 重症监护病房：创建、更新和管理库存单位
- 分类：分级分类管理
- 品牌：品牌创建和管理
- 规格：产品和SKU规格
💰 定价和促销
- API定价：基准价、标价、成本价和加价
- 计算价格：获取包括促销和税费在内的最终价格
- 促销：创建和管理所有类型的促销活动
- 优惠券：生成和管理折扣券
📊 库存与物流
- 库存：跨仓库的实时库存管理
- 仓库：创建和管理存储设施
- 码头：装卸码头配置
- 运输政策：配置配送方式和规则
🛒 订单管理
- 订单操作：查看、处理和更新订单
- 订单状态：通过工作流更改订单状态
- 开具发票：添加发票和跟踪信息
- 取消：取消订单并说明原因
🏪 市场运营
- 卖家管理：邀请和管理卖家
- 佣金：配置卖家佣金
- SKU审批：批准或拒绝卖家SKU
- 多卖家：完整的市场功能
🛍️ 结账和购物车（新！）
- 订单表：完整的购物车管理
- 航运模拟：计算运费和交货时间
- 购物车操作：添加、删除、更新项目
- 优惠券申请：将折扣券应用于购物车
- 购物车管理：清除购物车并管理订单
👥 客户数据（新增！）
- 主数据：完整的CRM功能
- 客户管理：创建、读取、更新、删除客户数据
- 文档管理：处理自定义数据实体
- 搜索和筛选：高级查询功能
- 客户查询：通过电子邮件和其他字段查找客户
🔍 产品搜索（新增！）
- 高级搜索：带过滤器的强大产品搜索
- 面板和过滤器：动态过滤器生成
- 自动完成：搜索建议
- 产品查询：按ID、EAN、参考、SKU查找
- 索引：散装产品和SKU ID检索
⭐ 评论与评分（新增！）
- 评审管理：创建、更新、删除评论
- 审批工作流程：批准或拒绝客户评论
- 评级统计：获取平均评级和分布
- 查看列表：筛选和排序评论
- 社会证明：通过评论建立客户信任
💳 付款配置（新增！）
- 支付提供商：配置支付网关
- 付款方式：管理可用的付款选项
- 交易跟踪：监控付款交易
- 供应商管理：添加、更新、删除支付集成
- 付款配置：完成网关设置
🎁 礼品卡（新版v1.5.0！）
- 礼品卡创建：创建带有余额和到期日的自定义礼品卡
- 礼品卡查询：按ID或兑换码检索
- 事务管理：在礼品卡上添加贷记或借记
- 礼品卡列表：查看所有带页码的礼品卡
- 限制：配置仅限所有者使用
- 用例：忠诚度计划、VIP重新激活、商店积分、退款
______________________________________________________________________
🚀 快速开始
通过npm安装（推荐）
npm install -g mcp-vtex配置
- 获取VTEX API证书:
- 导航到您的VTEX管理员→ 账户设置→ 账户 - 转到安全→ 应用程序密钥 - 创建新的应用密钥和应用令牌 - 安全地保存两个凭据
- 配置Claude桌面:
增添 ~/Library/Application Support/Claude/claude_desktop_config.json （Mac/Linux）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：
选项A-使用全局安装：
{
"mcpServers": {
"vtex": {
"command": "mcp-vtex",
"env": {
"VTEX_ACCOUNT_NAME": "your-account-name",
"VTEX_ENVIRONMENT": "vtexcommercestable",
"VTEX_APP_KEY": "your-app-key",
"VTEX_APP_TOKEN": "your-app-token"
}
}
}
}选项B-使用npx（始终是最新版本）：
{
"mcpServers": {
"vtex": {
"command": "npx",
"args": ["-y", "mcp-vtex"],
"env": {
"VTEX_ACCOUNT_NAME": "your-account-name",
"VTEX_ENVIRONMENT": "vtexcommercestable",
"VTEX_APP_KEY": "your-app-key",
"VTEX_APP_TOKEN": "your-app-token"
}
}
}
}- 配置光标:
添加到光标MCP设置（设置→ 扩展→ MCP):
{
"mcpServers": {
"vtex": {
"command": "npx",
"args": ["-y", "mcp-vtex"],
"env": {
"VTEX_ACCOUNT_NAME": "your-account-name",
"VTEX_ENVIRONMENT": "vtexcommercestable",
"VTEX_APP_KEY": "your-app-key",
"VTEX_APP_TOKEN": "your-app-token"
}
}
}
}- 重新启动克劳德桌面或光标
______________________________________________________________________
💬 使用示例
配置后，使用自然语言与VTEX交互：
目录管理
"Create a new product called 'Premium T-Shirt' in category 5 with brand 10""List all active SKUs for product 123""Update the price of SKU 456 to $29.99"库存操作
"Check inventory levels for SKU 789""Update inventory for SKU 101 in warehouse 1 to 50 units""List all warehouses"促销和定价
"Create a 20% discount promotion for Black Friday""Generate a coupon code 'WELCOME10' for new customers""Get the computed price for SKU 202 including all promotions"订单管理
"Get details for order v12345-01""List all orders from the last 7 days""Start handling order v12345-01""Add invoice 12345 with tracking ABC123 to order v12345-01"市场运营
"List all sellers in the marketplace""Approve SKU xyz from seller seller-123""Invite new seller 'Premium Store' with email seller@example.com"______________________________________________________________________
🛠️ 可用工具（164个工具）
API目录（30种工具）
- 产品：创建、获取、更新、删除、列表
- 重症监护病房：创建、获取、按参考ID获取、更新、列表
- 分类：创建、获取、更新、删除、列表
- 品牌：创建、获取、更新、删除、列表
- 规格：创建字段、创建规格、获取SKU规格、分配值、列出类别规格
定价API（5种工具）
- 获取价格、创建/更新价格、删除价格、列出价格、获取计算价格
库存API（3个工具）
- 获取库存、更新库存、按仓库列出库存
物流API（10个工具）
- 仓库：创建、获取、更新、删除、列表
- 码头：创建、获取、更新、删除、列表
促销和优惠券API（10个工具）
- 促销：创建、获取、更新、列表、存档、取消存档
- 优惠券：创建、获取、列出、存档
订单API（5个工具）
- 获取订单、列出订单、开始处理、取消订单、发票订单
市场API（7个工具）
- 获取/更新卖家佣金、获取SKU批准状态、批准SKU、拒绝SKU、邀请卖家、列出卖家
签出API（7个工具）🆕
- 获取订单、模拟发货、将商品添加到购物车、删除商品、更新数量、添加优惠券、清空购物车
主数据API（6个工具）🆕
- 创建文档、获取文档、更新文档、删除文档、搜索文档、通过电子邮件获取客户端
搜索API（5个工具）🆕
- 搜索产品，按标识符获取产品，获取产品和SKU ID，获取面，自动完成
评论和评级API（7个工具）🆕
- 创建评论、获取评论、列出评论、更新评论、删除评论、批准评论、获取审查摘要
支付网关API（7个工具）🆕
- 列出提供商、获取提供商、创建提供商、更新提供商、删除提供商、列出支付方式、获取交易
礼品卡API（5个工具）🎁 v1.5.0中的新功能！
- 创建礼品卡、获取礼品卡、列出礼品卡、按代码获取礼品卡，创建礼品卡交易
______________________________________________________________________
📁 项目结构
mcp-vtex/
├── src/
│ ├── index.ts # MCP server implementation
│ ├── vtex-client.ts # VTEX API client
│ └── types.ts # TypeScript definitions
├── dist/ # Compiled output
├── package.json
├── tsconfig.json
├── README.md
├── CHANGELOG.md
└── LICENSE______________________________________________________________________
🔧 发展
本地安装（用于开发）
# Clone repository
git clone https://github.com/leosepulveda/mcp-vtex.git
cd mcp-vtex
# Install dependencies
npm install
# Build
npm run build
# Development with auto-rebuild
npm run watch使用本地版本进行配置
适用于克劳德桌面，添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"vtex": {
"command": "node",
"args": ["/absolute/path/to/mcp-vtex/dist/index.js"],
"env": {
"VTEX_ACCOUNT_NAME": "your-account-name",
"VTEX_ENVIRONMENT": "vtexcommercestable",
"VTEX_APP_KEY": "your-app-key",
"VTEX_APP_TOKEN": "your-app-token"
}
}
}
}______________________________________________________________________
📋 需求
- Node.js：18岁或以上
- Vtex商店：活动VTEX帐户
- API证书：具有适当权限的应用密钥和应用令牌
- AI-IDE：支持MCP的Claude桌面或光标
所需的VTEX权限
您的应用密钥需要以下权限：
- 目录-完全访问
- 定价-完全访问
- 物流-完全访问
- OMS-完全访问
- 促销和税费-完全访问
- 市场-完全访问（如果使用市场功能）
______________________________________________________________________
🔐 安全最佳实践
- 从不提交凭据 到版本控制
- 将API凭据存储在环境变量中
- 定期旋转API键 出于安全考虑
- 使用单独的应用程序密钥进行开发和生产
- 限制权限 只提供每个密钥所需的内容
- 监控VTEX管理中API的使用情况
______________________________________________________________________
📊 API覆盖范围
此MCP服务器包含以下VTEX API：
✅ 目录API -完成\ ✅ API定价 -完成\ ✅ 库存与物流API -完成\ ✅ 促销和税收API -完成\ ✅ 订单管理API -核心功能\ ✅ 市场API -完成
______________________________________________________________________
🐛 故障排除
连接问题
问题：“无法连接到VTEX API”
- 验证
VTEX_ACCOUNT_NAME是正确的 - 检查应用密钥和应用令牌是否有效
- 确保您的VTEX商店处于活动状态
- 验证API凭据是否具有必要的权限
权限错误
问题：“权限不足”或“访问被拒绝”
- 在VTEX管理中检查应用程序密钥权限
- 确保应用密钥可以访问特定的API
- 某些操作需要管理员级别的权限
速率限制
问题：“请求太多”
- VTEX有每个API的费率限制
- 实施批量操作之间的延迟
- 尽可能考虑批处理操作
______________________________________________________________________
🤝 贡献
欢迎投稿！请随时提交拉取请求。
- 克隆该仓库
- 创建功能分支(
git checkout -b feature/AmazingFeature) - 提交您的更改(
git commit -m 'Add some AmazingFeature') - 推到分支(
git push origin feature/AmazingFeature) - 打开拉取请求
______________________________________________________________________
📝 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
______________________________________________________________________
🙏 致谢
- 立管式蒸发器试验装置 -电子商务平台
- Anthropic -Claude与模型上下文协议
- 光标 -AI驱动的代码编辑器
______________________________________________________________________
🔗 资源
______________________________________________________________________
📧 支持
- 问题:
- 讨论:
- VTEX社区: 社区.vtex.com
______________________________________________________________________
⚡ 环境变量
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
VTEX_ACCOUNT_NAME | 是 | - | 您的VTEX帐户名 |
VTEX_ENVIRONMENT | 没有 | vtexcommercestable | VTEX环境（通常为vtexcommercestable） |
VTEX_APP_KEY | 是 | - | 您的VTEX应用程序密钥 |
VTEX_APP_TOKEN | 是 | - | 您的VTEX应用令牌 |
______________________________________________________________________