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

---

🚀 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

Variable	Required	Default	Description
VTEX_ACCOUNT_NAME	Yes	-	Your VTEX account name
VTEX_ENVIRONMENT	No	vtexcommercestable	VTEX environment (usually vtexcommercestable)
VTEX_APP_KEY	Yes	-	Your VTEX App Key
VTEX_APP_TOKEN	Yes	-	Your VTEX App Token

---

<div align="center">

⬆ Back to Top

</div>