VTEX MCP Server

MCP (Model Context Protocol) server for VTEX API integration.

Features

• Read-Only Operations: All tools are GET-only for safety
• YAML Responses: Optimized token usage with YAML format instead of JSON
• PII Protection: Automatic removal of sensitive customer data (enabled by default)
• Catalog API: Access product and SKU information
• Orders API: Retrieve order data
• Pricing API: Access pricing and fixed prices
• Logistics API: Access inventory and logistics information

Configuration

Environment Variables

This MCP server requires the following environment variables:

• VTEX_ACCOUNT_NAME: Your VTEX account name
• VTEX_APP_KEY: Your VTEX App Key
• VTEX_APP_TOKEN: Your VTEX App Token
• VTEX_ENVIRONMENT: VTEX environment (default: vtexcommercestable)
• VTEX_PII_PROTECTION: Enable PII filtering (default: true, set to "false" to disable)

VTEX App Key Permissions

Configure the following permissions in your VTEX App Key (Account Settings → Account → App Keys):

📦 Catalog (Product: Catalog)

Required permissions:

• ✅ Product management
• ✅ Product and SKU Management
• ✅ Category
• ✅ SKUs

📋 Orders (Product: OMS)

Required permissions:

• ✅ Viewer role or higher

💰 Pricing (Product: Pricing)

Required permissions:

• ✅ Viewer role or higher

🚚 Logistics (Product: Logistics)

Required permissions:

• ✅ Viewer role or higher

Note: All operations in this MCP are read-only (GET requests only), but VTEX may require admin-level permissions even for read operations depending on your account configuration.

Available Prompts

Prompts são workflows pré-definidos que guiam análises complexas:

1. analyze-sku-complete - Análise 360° de um SKU (estoque + preço + insights)
2. analyze-product-performance - Performance de produto com todas variações
3. compare-prices - Comparação de preços entre tabelas
4. inventory-report - Relatório completo de inventário
5. order-analysis - Análise detalhada de pedido
6. product-catalog-overview - Visão geral do catálogo
7. pricing-strategy-review - Revisão da estratégia de preços
8. logistics-setup-review - Análise da configuração logística

Available Tools

Catalog Tools (5)

• vtex_catalog_get_product: Get product details by ID
• vtex_catalog_list_products: List products with pagination
• vtex_catalog_get_sku: Get SKU details by ID
• vtex_catalog_get_product_variations: Get product variations
• vtex_catalog_get_category_tree: Get category tree structure

Orders Tools (3)

• vtex_orders_get_order: Get order details by ID
• vtex_orders_list_orders: List orders with filters
• vtex_orders_get_order_group: Get order group details

Pricing Tools (6)

• vtex_pricing_get_price: Get price information for a SKU
• vtex_pricing_get_fixed_prices: Get all fixed prices for a SKU
• vtex_pricing_get_fixed_price_by_table: Get fixed price in specific price table
• vtex_pricing_get_computed_price: Get computed price in specific price table
• vtex_pricing_get_config: Get pricing configuration
• vtex_pricing_list_price_tables: List all price tables

Inventory/Logistics Tools (6)

• vtex_inventory_get_by_sku: Get inventory for a SKU across all warehouses
• vtex_inventory_get_by_warehouse: Get inventory for a SKU in specific warehouse
• vtex_inventory_list_warehouses: List all warehouses
• vtex_inventory_get_warehouse: Get warehouse details
• vtex_inventory_list_docks: List all docks
• vtex_inventory_get_dock: Get dock details

API Endpoints Used

This MCP server uses the following VTEX API endpoints (20 total):

📦 Catalog API (5 endpoints)

• /api/catalog/pvt/product/{productId} - Get product details
• /api/catalog/pvt/stockkeepingunit/{skuId} - Get SKU details
• /api/catalog_system/pvt/products/GetProductAndSkuIds - List products with pagination
• /api/catalog_system/pub/products/variations/{productId} - Get product variations
• /api/catalog_system/pub/category/tree/{levels} - Get category tree

📋 Orders API (3 endpoints)

• /api/oms/pvt/orders/{orderId} - Get order by ID
• /api/oms/pvt/orders - List orders with filters
• /api/oms/pvt/orders/order-group/{orderGroup} - Get order group

💰 Pricing API (6 endpoints)

• /api/pricing/prices/{itemId} - Get price by SKU
• /api/pricing/prices/{itemId}/fixed - Get all fixed prices
• /api/pricing/prices/{itemId}/fixed/{priceTableId} - Get fixed price by table
• /api/pricing/prices/{itemId}/computed/{priceTableId} - Get computed price
• /api/pricing/config - Get pricing configuration
• /api/pricing/tables - List price tables

🚚 Inventory/Logistics API (6 endpoints)

• /api/logistics/pvt/inventory/skus/{skuId} - Get inventory by SKU
• /api/logistics/pvt/inventory/items/{skuId}/warehouses/{warehouseId} - Get inventory by warehouse
• /api/logistics/pvt/configuration/warehouses - List warehouses
• /api/logistics/pvt/configuration/warehouses/{warehouseId} - Get warehouse details
• /api/logistics/pvt/configuration/docks - List docks
• /api/logistics/pvt/configuration/docks/{dockId} - Get dock details

🔐 PII Protection

This MCP server includes automatic PII (Personally Identifiable Information) protection to ensure sensitive customer data is not exposed to LLMs.

What is Protected?

The following types of data are automatically removed from API responses:

👤 Personal Information

• First/Last names (firstName, lastName, receiverName, cardHolder, clientName)
• Corporate names (corporateName, tradeName)

📧 Contact Information

• Email addresses (email, followUpEmail)
• Phone numbers (phone, cellPhone, corporatePhone)

🆔 Documents & IDs

• Personal documents (document, cpf, cnpj)
• Corporate documents (corporateDocument, stateInscription)

🏠 Address Information

• Full address objects (address, billingAddress, location)
• Address components (street, number, complement, neighborhood, postalCode, city, state)
• Geographic coordinates (geoCoordinates, latitude, longitude, point, coordinates)

💳 Payment Information

• Card holder names (cardHolder)
• Card numbers (cardNumber, firstDigits, lastDigits)
• Security codes (cvv, cvv2)
• Expiration dates (expireMonth, expireYear)

What is Preserved?

✅ All ID fields are preserved for reference and correlation:

• orderId, userId, userProfileId
• addressId, transactionId, paymentId
• productId, skuId, warehouseId, dockId
• All other fields ending in Id

✅ Business data remains intact:

• Order values, quantities, prices
• Status codes, dates, timestamps
• Product names, descriptions, SKUs
• Business hours, configuration flags
• Warehouse/dock names (business entities)

Configuration

PII protection is enabled by default. To disable it (not recommended):

export VTEX_PII_PROTECTION=false

Example: Before and After Filtering

Before (Original API Response):

clientProfileData:
  id: clientProfileData
  email: [email protected]        # ❌ PII
  firstName: João                       # ❌ PII
  lastName: Silva                       # ❌ PII
  document: 123.456.789-00              # ❌ PII
  phone: +5511999999999                 # ❌ PII
  userProfileId: user-abc-123           # ✅ Safe ID

After (Filtered Response):

clientProfileData:
  id: clientProfileData
  documentType: cpf                     # ✅ Type code (safe)
  userProfileId: user-abc-123           # ✅ ID preserved
  isCorporate: false                    # ✅ Flag (safe)

Benefits

• 🛡️ LGPD/GDPR Compliance: Sensitive data never reaches the LLM
• 💰 Token Efficiency: Less data = lower costs
• 🔒 Privacy by Design: PII filtered at source
• ⚡ Simple & Fast: No complex masking or pseudonymization
• ✅ Maintains Functionality: IDs allow for correlation and lookups

Testing

Run the PII protection test suite:

node test-pii-filter.js

This validates that all PII is removed while IDs are preserved.

Installation

For Development

npm install

For Claude Desktop

1. Download the latest .mcpb file from Releases
2. Open Claude Desktop
3. Go to Settings → Developer → MCP Servers
4. Click "Install from file" and select the downloaded .mcpb file
5. Configure your VTEX credentials
6. Enable the server

Usage

This MCP server is designed to be used with Claude Desktop or other MCP clients.

Using Prompts

After installation, you can use pre-built prompts in Claude Desktop:

"Use the analyze-sku-complete prompt for SKU 12345"
"Run the inventory-report prompt for SKU 67890"

Using Tools Directly

Or call tools directly:

"Get product details for product ID 123 using vtex_catalog_get_product"
"List the last 10 orders"

License

MIT