# MCP VTEX Server
[](https://www.npmjs.com/package/mcp-vtex)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://vtex.com)
**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)
```bash
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:**
```json
{
"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):**
```json
{
"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):
```json
{
"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
```plaintext
"Create a new product called 'Premium T-Shirt' in category 5 with brand 10"
```
```plaintext
"List all active SKUs for product 123"
```
```plaintext
"Update the price of SKU 456 to $29.99"
```
### Inventory Operations
```plaintext
"Check inventory levels for SKU 789"
```
```plaintext
"Update inventory for SKU 101 in warehouse 1 to 50 units"
```
```plaintext
"List all warehouses"
```
### Promotions & Pricing
```plaintext
"Create a 20% discount promotion for Black Friday"
```
```plaintext
"Generate a coupon code 'WELCOME10' for new customers"
```
```plaintext
"Get the computed price for SKU 202 including all promotions"
```
### Order Management
```plaintext
"Get details for order v12345-01"
```
```plaintext
"List all orders from the last 7 days"
```
```plaintext
"Start handling order v12345-01"
```
```plaintext
"Add invoice 12345 with tracking ABC123 to order v12345-01"
```
### Marketplace Operations
```plaintext
"List all sellers in the marketplace"
```
```plaintext
"Approve SKU xyz from seller seller-123"
```
```plaintext
"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)
```bash
# 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`:
```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](LICENSE) file for details.
---
## š Acknowledgments
- **[VTEX](https://vtex.com)** - E-commerce platform
- **[Anthropic](https://anthropic.com)** - Claude and Model Context Protocol
- **[Cursor](https://cursor.sh)** - AI-powered code editor
---
## š Resources
- [VTEX Developer Portal](https://developers.vtex.com/)
- [VTEX API Documentation](https://developers.vtex.com/docs/api-reference)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP Servers Registry](https://github.com/modelcontextprotocol/servers)
---
## š§ Support
- **Issues**: [GitHub Issues](https://github.com/leosepulveda/mcp-vtex/issues)
- **Discussions**: [GitHub Discussions](https://github.com/leosepulveda/mcp-vtex/discussions)
- **VTEX Community**: [community.vtex.com](https://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](#mcp-vtex-server)**
</div>
