MCP VTEX Server

Complete VTEX API integration for Claude Desktop and Cursor - Manage your entire e-commerce operation through AI conversations. Control catalog, inventory, pricing, promotions, orders, and marketplace operations with natural language.

✨ Features

📦 Catalog Management

• Products: Full CRUD operations for products

• SKUs: Create, update, and manage stock keeping units

• Categories: Hierarchical category management

• Brands: Brand creation and management

• Specifications: Product and SKU specifications

💰 Pricing & Promotions

• Pricing API: Base prices, list prices, cost prices, and markup

• Computed Prices: Get final prices including promotions and taxes

• Promotions: Create and manage all types of promotions

• Coupons: Generate and manage discount coupons

📊 Inventory & Logistics

• Inventory: Real-time stock management across warehouses

• Warehouses: Create and manage storage facilities

• Docks: Loading dock configuration

• Shipping Policies: Configure shipping methods and rules

🛒 Orders Management

• Order Operations: View, process, and update orders

• Order Status: Change order status through workflow

• Invoicing: Add invoices and tracking information

• Cancellations: Cancel orders with reasons

🏪 Marketplace Operations

• Seller Management: Invite and manage sellers

• Commissions: Configure seller commissions

• SKU Approval: Approve or deny seller SKUs

• Multi-seller: Full marketplace functionality

🛍️ Checkout & Cart (NEW!)

• Order Form: Complete cart management

• Shipping Simulation: Calculate shipping costs and delivery times

• Cart Operations: Add, remove, update items

• Coupon Application: Apply discount coupons to cart

• Cart Management: Clear cart and manage order form

👥 Customer Data (NEW!)

• Master Data: Full CRM functionality

• Client Management: Create, read, update, delete customer data

• Document Management: Handle custom data entities

• Search & Filter: Advanced query capabilities

• Client Lookup: Find customers by email and other fields

🔍 Product Search (NEW!)

• Advanced Search: Powerful product search with filters

• Facets & Filters: Dynamic filter generation

• Autocomplete: Search suggestions

• Product Lookup: Find by ID, EAN, Reference, SKU

• Indexing: Bulk product and SKU ID retrieval

⭐ Reviews & Ratings (NEW!)

• Review Management: Create, update, delete reviews

• Approval Workflow: Approve or reject customer reviews

• Rating Statistics: Get average ratings and distributions

• Review Listing: Filter and sort reviews

• Social Proof: Build customer trust with reviews

💳 Payment Configuration (NEW!)

• Payment Providers: Configure payment gateways

• Payment Methods: Manage available payment options

• Transaction Tracking: Monitor payment transactions

• Provider Management: Add, update, remove payment integrations

• Payment Configuration: Complete gateway setup

🎁 Gift Cards (NEW v1.5.0!)

• Gift Card Creation: Create custom gift cards with balance and expiration

• Gift Card Lookup: Retrieve by ID or redemption code

• Transaction Management: Add credits or debits to gift cards

• Gift Card Listing: View all gift cards with pagination

• Restrictions: Configure owner-only usage

• Use Cases: Loyalty programs, VIP reactivation, store credit, refunds

Related MCP server: ecommerce-mcp

🚀 Quick Start

Installation via npm (Recommended)

npm install -g mcp-vtex

Configuration

1. Get your VTEX API credentials:

   • Navigate to your VTEX Admin → Account Settings → Account

   • Go to Security → Application Keys

   • Create a new App Key and App Token

   • Save both credentials securely

2. Configure Claude Desktop:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Option A - Using global installation:

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

Option B - Using npx (always latest version):

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

3. Configure Cursor:

Add to Cursor MCP settings (Settings → Extensions → 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"
      }
    }
  }
}

4. Restart Claude Desktop or Cursor

💬 Usage Examples

Once configured, interact with VTEX using natural language:

Catalog Management

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

Inventory Operations

"Check inventory levels for SKU 789"

"Update inventory for SKU 101 in warehouse 1 to 50 units"

"List all warehouses"

Promotions & Pricing

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

Order Management

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

Marketplace Operations

"List all sellers in the marketplace"

"Approve SKU xyz from seller seller-123"

"Invite new seller 'Premium Store' with email seller@example.com"

🛠️ Available Tools (164 Tools)

Catalog API (30 tools)

• Products: Create, Get, Update, Delete, List

• SKUs: Create, Get, Get by RefId, Update, List

• Categories: Create, Get, Update, Delete, List

• Brands: Create, Get, Update, Delete, List

• Specifications: Create Field, Create Spec, Get SKU Specs, Assign Values, List Category Specs

Pricing API (5 tools)

• Get Price, Create/Update Price, Delete Price, List Prices, Get Computed Price

Inventory API (3 tools)

• Get Inventory, Update Inventory, List Inventory by Warehouse

Logistics API (10 tools)

• Warehouses: Create, Get, Update, Delete, List

• Docks: Create, Get, Update, Delete, List

Promotions & Coupons API (10 tools)

• Promotions: Create, Get, Update, List, Archive, Unarchive

• Coupons: Create, Get, List, Archive

Orders API (5 tools)

• Get Order, List Orders, Start Handling, Cancel Order, Invoice Order

Marketplace API (7 tools)

• Get/Update Seller Commissions, Get SKU Approval Status, Approve SKU, Deny SKU, Invite Seller, List Sellers

Checkout API (7 tools) 🆕

• Get Order Form, Simulate Shipping, Add Item to Cart, Remove Item, Update Quantity, Add Coupon, Clear Cart

Master Data API (6 tools) 🆕

• Create Document, Get Document, Update Document, Delete Document, Search Documents, Get Client by Email

Search API (5 tools) 🆕

• Search Products, Get Product by Identifier, Get Product & SKU IDs, Get Facets, Autocomplete

Reviews and Ratings API (7 tools) 🆕

• Create Review, Get Review, List Reviews, Update Review, Delete Review, Approve Review, Get Review Summary

Payment Gateway API (7 tools) 🆕

• List Providers, Get Provider, Create Provider, Update Provider, Delete Provider, List Payment Methods, Get Transaction

Gift Card API (5 tools) 🎁 NEW in v1.5.0!

• Create Gift Card, Get Gift Card, List Gift Cards, Get Gift Card by Code, Create Gift Card Transaction

📁 Project Structure

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

🔧 Development

Local Installation (For Development)

# 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

Configure with Local Build

For Claude Desktop, add to ~/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"
      }
    }
  }
}

📋 Requirements

• Node.js: 18 or higher

• VTEX Store: Active VTEX account

• API Credentials: App Key and App Token with appropriate permissions

• AI IDE: Claude Desktop or Cursor with MCP support

Required VTEX Permissions

Your App Key needs the following permissions:

• Catalog - Full Access

• Pricing - Full Access

• Logistics - Full Access

• OMS - Full Access

• Promotions & Taxes - Full Access

• Marketplace - Full Access (if using marketplace features)

🔐 Security Best Practices

• Never commit credentials to version control

• Store API credentials in environment variables

• Rotate API keys regularly for security

• Use separate App Keys for development and production

• Limit permissions to only what's needed for each key

• Monitor API usage in VTEX Admin

📊 API Coverage

This MCP server covers the following VTEX APIs:

✅ Catalog API - Complete
✅ Pricing API - Complete
✅ Inventory & Logistics API - Complete
✅ Promotions & Taxes API - Complete
✅ Orders Management API - Core features
✅ Marketplace API - Complete

🐛 Troubleshooting

Connection Issues

Problem: "Cannot connect to VTEX API"

• Verify VTEX_ACCOUNT_NAME is correct

• Check that App Key and App Token are valid

• Ensure your VTEX store is active

• Verify API credentials have necessary permissions

Permission Errors

Problem: "Insufficient permissions" or "Access denied"

• Check App Key permissions in VTEX Admin

• Ensure the App Key has access to the specific API

• Some operations require admin-level permissions

Rate Limiting

Problem: "Too many requests"

• VTEX has rate limits per API

• Implement delays between bulk operations

• Consider batching operations when possible

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• VTEX - E-commerce platform

• Anthropic - Claude and Model Context Protocol

• Cursor - AI-powered code editor

🔗 Resources

• VTEX Developer Portal

• VTEX API Documentation

• Model Context Protocol

• MCP Servers Registry

📧 Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

• VTEX Community: community.vtex.com

⚡ Environment Variables

⬆ Back to Top