VTEX
About
VTEX MCP Server serves as a wrapper for VTEX Commerce APIs, enabling e-commerce analytics for store owners. It facilitates various business intelligence tasks using an LLM client, such as Claude Desktop.
Details
- Author
- jamesm010
- Downloads
- 479
- Categories
- AI
Jump to
- Comprehensive analytics for performance ranking, trend analysis, and competitive insights.
- Advanced order search, filtering, and aggregation with multi-dimensional statistics.
- Complete business health snapshots with key metrics in a single call.
- Automatic discovery of available filter values for accurate analytics filtering.
- Token-optimized data formats designed for AI/LLM consumption.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
VTEXCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Obtain API credentials from your VTEX admin panel, then configure your Claude Desktop application by adding your app key, app token, and account name to claude_desktop_config.json using the vtex-mcp command via npx.
get_orders_count
Get order counts across different time periods: today (current day orders), yesterday (previous day orders), lastWeek (same day last week orders), lastMonth (same day last month orders), lastYear (same day last year orders). Note: This tool provides pre-calculated counts for specific time periods and does not use date range parameters. The "lastYear" count refers to the same day of the year in the previous year, not a 90-day range. Timezone parameter is optional and defaults to EST (-5). Use this for quick time-based comparisons without date range limitations.
search_orders
Returns INDIVIDUAL ORDER RECORDS with full details for REVENUE-GENERATING ORDERS. By DEFAULT filters for revenue orders only: "payment-approved,ready-for-handling,handling,invoiced". Use when you need: specific order information, customer details, order tracking for completed sales. NOT for aggregated metrics or business analysis. Supports full-text search, datetime formats (YYYY-MM-DDTHH:MM:SS), timezone conversion, status filtering, and all VTEX OMS filter parameters. Common usage patterns: • Revenue orders (default): automatically includes only orders that count as sales • All statuses: set f_status="" to include all order statuses (canceled, payment-pending, etc.) • Specific status: use "f_status" to override default (e.g., "canceled", "payment-pending") • Full-text search: use "q" parameter (searches order ID, client name, email) • Date range: use "startDate" and "endDate" with optional "timezone" (e.g., "America/Bogota") • Recent orders: call without filters for latest revenue orders Each query retrieves up to 90 days of orders. For longer periods (e.g., annual order analysis), make multiple calls with consecutive 90-day ranges. Returns paginated data as JSON tuples for token efficiency. Response includes pagination metadata: ["meta", "type", "paginated_data"], ["meta", "currentPage", N], ["meta", "totalPages", N], ["meta", "totalOrders", N], ["meta", "hasMoreData", 0/1]. Each order tuple contains: [orderId, creationEpoch, clientName, totalValue, paymentNames, status, salesChannel, origin]. Use "page" parameter to navigate through results when hasMoreData=1.
aggregate_order_data
Returns AGGREGATED METRICS and counts (totals, averages, summaries). Use when you need: totals by category, comparative analysis, business intelligence. NOT for individual order details. Perfect for both simple counts and complex business intelligence with datetime formats (YYYY-MM-DDTHH:MM:SS) and timezone support. Key use cases: • Basic Counts & Metrics: Count orders by any filter (payment method, status, date range, etc.), get totals for revenue and orders across any dimension, answer questions like "how many PSE orders?" or "how many canceled orders?" • Comparative Analysis: Compare performance between payment methods, channels, sellers, analyze customer behavior patterns across segments, identify growth/decline trends by category • Business Intelligence: Strategic insights for decision-making and performance monitoring, campaign and promotion effectiveness analysis, operational KPI tracking and benchmarking Each query aggregates up to 90 days of data. For longer analysis (e.g., yearly payment method trends), make multiple calls with consecutive 90-day ranges. Returns complete aggregated data in [category, dimension, value, count] format optimized for token efficiency. Response includes metadata: ["meta", "type", "aggregated_data"], ["meta", "totalFacetGroups", N], ["meta", "totalItems", N], ["meta", "isPaginated", 0]. Key distinction: Provides aggregated insights vs. search_orders which returns individual records.
breakdown_metrics_by_dimension
Ranks and compares performance within business dimensions (brands, categories, products, payment methods, etc.). Shows top/bottom performers with period-over-period growth analysis. Perfect for questions like "which are my top-selling brands?" or "what products are declining?" Key use cases: • Performance ranking: Find top-selling brands, categories, or products by revenue/orders • Growth analysis: Identify fastest growing/declining items with period-over-period comparisons • Competitive insights: Compare performance between different items within the same dimension • Trend identification: Spot emerging opportunities or declining segments Each query analyzes up to 90 days. For longer periods (e.g., 2-year brand analysis), make multiple calls with consecutive 90-day ranges. OPTIONAL: Call get_filter_options first if you need to discover available filter values for accurate filtering. Returns ranked lists with growth metrics as [itemName, metricName, currentValue, previousValue, percentChange] tuples. Response includes pagination metadata: ["meta", "totalItems", N], ["meta", "returnedItems", N], ["meta", "hasMoreData", 0/1], ["meta", "estimatedPages", N]. Use "itemsPerPage" parameter to control results. When hasMoreData=1, increase itemsPerPage or apply filters to get more specific results. Essential for performance benchmarking and competitive analysis.
get_filter_options
Discovers available filter values for any business dimension (brands, categories, products, payment methods, etc.). Essential prerequisite for accurate filtering in other analytics tools. Use this when you need exact filter values for filtering in breakdown_metrics_by_dimension. Key use cases: • Find exact names: Get precise spelling/format of brands, categories, or products • Explore catalog: Discover what dimensions exist in your data (e.g., find all payment methods) • Validate filters: Ensure filter values exist before using in other analytics tools • Data discovery: Understand available segments for analysis Each query analyzes up to 90 days. For longer periods, make multiple calls with consecutive 90-day ranges. Returns complete dimension data as [optionValue, optionId] tuples. Response includes metadata: ["meta", "type", "dimension_options"], ["meta", "totalOptions", N], ["meta", "isPaginated", 0]. This provides complete data for the specified dimension and date range.
track_conversion_trends
Retrieves conversion rate data over time with period-over-period comparisons. Shows how website conversion performance changes across different time periods. Essential for measuring campaign impact and identifying conversion patterns. Key use cases: • Performance monitoring: Track daily/weekly conversion rate changes • Campaign impact: Measure conversion rate before/during/after campaigns • Trend analysis: Identify conversion rate patterns and seasonal effects • Benchmarking: Compare current performance vs historical periods Each query analyzes up to 90 days. For longer trend analysis (e.g., yearly patterns), make multiple calls with consecutive 90-day ranges. Aggregation parameter controls data grouping: "hour" for hourly data points, "day" for daily summaries, "week" for weekly summaries. Returns overall conversion rates plus time-series data showing trends. Data format: [referenceEpoch, comparedEpoch, currentRate, previousRate, percentChange] tuples.
get_performance_overview
Get comprehensive business health snapshot with all key metrics (revenue, orders, AOV, conversion rate, sessions) in a single call. Perfect for executive dashboards and quick performance checks. Provides complete store performance overview with period-over-period comparisons. Key use cases: • Executive dashboards: Get all key KPIs in one call • Performance monitoring: Track overall business health metrics • Quick diagnostics: Answer questions like "What's our AOV?" or "How are we performing?" • Trend analysis: See if key metrics are improving or declining • Business reporting: Get formatted data for reports and presentations Each query analyzes up to 90 days. For longer performance tracking (e.g., quarterly reports), make multiple calls with consecutive 90-day ranges. Aggregation parameter controls data grouping: "hour" for hourly data points, "day" for daily summaries, "week" for weekly summaries. Returns structured JSON with current values, previous period values, and percentage changes for each metric. Includes revenue, order count, average order value, sessions, and calculated conversion rate.
list_brands
Retrieve paginated list of brands from the VTEX store catalog. Perfect for browsing available brands, analyzing brand portfolio, or finding specific brand information. Key use cases: • Brand discovery: Find all available brands in the store • Brand analysis: Check which brands are active vs inactive • Brand validation: Verify if a specific brand exists in the catalog • Inventory planning: Review brand portfolio for merchandising decisions No date range limitations - provides static catalog data. Returns data as JSON tuples for token efficiency. First tuple contains pagination info: ["paging", currentPage, totalPages, totalBrands]. Each brand tuple contains: [brandId, brandName, isActive]. Default page size is 30 brands. Use pagination to browse through large brand catalogs efficiently.
get_category_tree
Retrieve the category tree structure from the VTEX store catalog. Perfect for understanding product categorization, building navigation menus, or analyzing category hierarchy. Key use cases: • Category discovery: Explore the complete category structure • Navigation building: Generate menu structures for storefronts • Category analysis: Understand how products are organized • Inventory planning: Review category coverage and gaps No date range limitations - provides static catalog data. Specify categoryLevels to control tree depth (default: 3 levels, max: 3). Returns data as JSON tuples for token efficiency. Each category tuple contains: [level, categoryId, categoryName, hasChildren, childrenCount]. Child categories are included as nested tuples with increasing level numbers.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"vtex": {
"vtex": {
"command": "npx",
"args": [
"vtex-mcp",
"--appKey",
"<YOUR_APP_KEY>",
"--appToken",
"<YOUR_APP_TOKEN>",
"--account",
"<YOUR_VTEX_ACCOUNT_NAME>"
]
}
}
}
}McpServers
{
"vtex": {
"command": "npx",
"args": [
"vtex-mcp",
"--appKey",
"<YOUR_APP_KEY>",
"--appToken",
"<YOUR_APP_TOKEN>",
"--account",
"<YOUR_VTEX_ACCOUNT_NAME>"
]
}
}what is VTEX MCP Server?
VTEX MCP Server is an API that enables e-commerce analytics and order management through the VTEX platform. It facilitates various business intelligence tasks using a user-friendly interface for enterprise e-commerce operations.
how to use VTEX MCP Server?
To use the VTEX MCP Server, obtain API credentials from your VTEX admin panel, configure your Claude Desktop application to include your credentials and account information, and employ the various analytics and order management tools for specific tasks like performance analysis and order tracking.
key features of VTEX MCP Server?
Business Intelligence Tools: Comprehensive analytics for performance ranking, trend analysis, and competitive insights across brands, categories, products, and more.
Order Management: Advanced order search, filtering, and aggregation capabilities with multi-dimensional statistics.
Performance Overview: Complete business health snapshots with all key metrics (revenue, orders, AOV, conversion rate, sessions) in single calls.
Filter Discovery: Automatic discovery of available filter values for accurate analytics filtering and data exploration.
Token-Optimized Data: Efficient data formats optimized for AI/LLM consumption with tuple structures and metadata.
use cases of VTEX MCP Server?
Managing VTEX e-commerce performance analytics programmatically.
Automating business intelligence reporting and KPI monitoring across multiple store dimensions.
Facilitating data-driven decision making through order pattern analysis and sales performance tracking.
Identifying top/bottom performers, growth trends, and optimization opportunities in real-time.
Configuration
Claude Desktop Setup
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"vtex": {
"command": "npx",
"args": [
"vtex-mcp",
"--appKey",
"<YOUR_APP_KEY>",
"--appToken",
"<YOUR_APP_TOKEN>",
"--account",
"<YOUR_VTEX_ACCOUNT_NAME>"
]
}
}
}
Config file locations:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
Available Tools
Analytics Tools
get_performance_overview - Get comprehensive business health snapshot with all key metrics in a single call
breakdown_metrics_by_dimension - Rank and compare performance within business dimensions (brands, categories, products, etc.)
get_filter_options - Discover available filter values for any business dimension
track_conversion_trends - Retrieve conversion rate data over time with period-over-period comparisons
Order Tools
get_orders_count - Get order counts across different time periods (today, yesterday, last week, etc.)
search_orders - Search and filter orders with comprehensive filtering options for individual order details
aggregate_order_data - Retrieve business metrics and aggregated order data with multi-dimensional statistics
FAQ from VTEX MCP Server?
How do I obtain VTEX API credentials?
Visit your VTEX admin panel > Account Settings > API Keys > Generate Keys. Select necessary read permissions for Orders, Catalog, Customer Data, and Analytics.
What's the difference between search_orders and aggregate_order_data?
Use search_orders when you need individual order details and records. Use aggregate_order_data when you need summarized metrics, counts, and business intelligence insights.
How do I find exact filter values for analytics tools?
Always use get_filter_options first to discover available filter values before using breakdown_metrics_by_dimension for accurate filtering and analysis.
Is there a limit on the date ranges I can query?
Yes, date ranges are limited to a maximum of 90 days for all analytics and order tools to ensure optimal performance.
Can I use VTEX MCP Server for any VTEX store?
Yes! The server works with any VTEX store account. Just provide your specific account name, app key, and app token in the configuration.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
