Volve-Tech/vtex-mcp-server

VTEX MCP Server

A comprehensive Model Context Protocol (MCP) server for VTEX APIs, enabling AI assistants to interact with the VTEX e-commerce platform through 163+ API endpoints.

🚀 Features

• Complete VTEX API Coverage: Access to 163+ VTEX API endpoints
• Type-Safe: Built with TypeScript following SOLID principles
• MCP Protocol: Fully compliant with Model Context Protocol specifications
• Easy Configuration: Simple environment-based configuration
• Category Organization: APIs organized by functional categories (SKU Service, Catalog, Orders, etc.)
• Comprehensive Error Handling: Robust error handling and logging

📦 Installation

From npm (when published)

npm install -g vtex-mcp-server

From source

git clone https://github.com/Volve-Tech/vtex-mcp-server.git
cd vtex-mcp-server
npm install
npm run build

⚙️ Configuration

Create a .env file in the project root or set environment variables:

VTEX_ACCOUNT_NAME=your-account-name
VTEX_API_KEY=your-api-key
VTEX_API_TOKEN=your-api-token
VTEX_ENVIRONMENT=vtexcommercestable

Getting VTEX API Credentials

1. Account Name: Your VTEX store account name (e.g., if your store is mystore.vtexcommercestable.com.br, the account name is mystore)

2. API Key and Token:

   • Access your VTEX Admin panel
   • Navigate to Account Settings > Account > Security
   • Go to Application Keys
   • Click Generate New Key
   • Save both the App Key (API Key) and App Token (API Token)

🔧 Usage

As a Standalone Server

npm start

With MCP Clients

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vtex": {
      "command": "node",
      "args": ["/path/to/vtex-mcp-server/dist/index.js"],
      "env": {
        "VTEX_ACCOUNT_NAME": "your-account-name",
        "VTEX_API_KEY": "your-api-key",
        "VTEX_API_TOKEN": "your-api-token",
        "VTEX_ENVIRONMENT": "vtexcommercestable"
      }
    }
  }
}

Using npx (after publishing)

{
  "mcpServers": {
    "vtex": {
      "command": "npx",
      "args": ["vtex-mcp-server"],
      "env": {
        "VTEX_ACCOUNT_NAME": "your-account-name",
        "VTEX_API_KEY": "your-api-key",
        "VTEX_API_TOKEN": "your-api-token"
      }
    }
  }
}

📚 Available API Categories

The server provides access to the following VTEX API categories:

• SKU Service: Manage SKU services, types, values, and attachments
• Catalog:
  • Categories (tree, CRUD operations)
  • Brands (list, paginated list, CRUD operations)
  • Attachments (CRUD operations)
  • Products (CRUD, specifications, reviews, trade policies)
  • SKUs (variations, specifications)
• Orders: Order management and fulfillment
• Pricing: Price management and rules
• Logistics: Shipping, inventory, and docks
• Promotions: Discount and promotion management
• Customer: Customer data and segmentation
• Payments: Payment methods and transactions
• And many more...

🛠️ Development

Project Structure

vtex-mcp-server/
├── src/
│   ├── config/          # Configuration management
│   │   └── VtexConfig.ts
│   ├── interfaces/      # TypeScript interfaces
│   │   ├── IVtexConfig.ts
│   │   ├── IVtexRequest.ts
│   │   └── IApiClient.ts
│   ├── models/          # Domain models
│   │   └── VtexEndpoint.ts
│   ├── services/        # API client services
│   │   └── VtexApiClient.ts
│   ├── tools/           # MCP tool implementation
│   │   ├── VtexToolFactory.ts
│   │   └── VtexToolHandler.ts
│   ├── utils/           # Utility functions
│   │   └── postmanParser.ts
│   ├── data/            # Generated endpoint definitions
│   │   └── endpoints.ts
│   └── index.ts         # Main server entry point
├── dist/                # Compiled JavaScript
├── postman-collection (1).json  # Source API definitions
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Development Mode (watch)

npm run dev

Regenerating Endpoints

If you update the Postman collection, regenerate the endpoints:

node -e "require('./dist/utils/postmanParser.js').regenerateEndpoints()"

🏗️ Architecture

This project follows SOLID principles:

• Single Responsibility: Each class has a single, well-defined purpose
• Open/Closed: Extensible through interfaces without modifying existing code
• Liskov Substitution: Interfaces define clear contracts
• Interface Segregation: Focused, minimal interfaces
• Dependency Inversion: Dependencies on abstractions, not concrete implementations

Key Components

1. VtexConfig: Manages configuration and environment variables
2. VtexApiClient: Handles HTTP communication with VTEX APIs
3. VtexEndpoint: Represents API endpoint metadata
4. VtexToolFactory: Creates MCP tools from endpoints
5. VtexToolHandler: Executes tool calls and manages requests
6. MCP Server: Coordinates all components and handles MCP protocol

🔒 Security

• API Credentials: Never commit .env file or expose credentials
• Environment Variables: All sensitive data should be in environment variables
• HTTPS: All API requests use HTTPS
• Token Rotation: Regularly rotate your API keys and tokens

📝 Example Tool Calls

Once configured, you can interact with VTEX APIs through your MCP client:

"Get product by ID 123"
"List all brands"
"Get SKU service 5"
"Update category 10"
"Create a new product"

The AI assistant will automatically map these requests to the appropriate VTEX API tools.

🤝 Contributing

See for details on:

• Code style and standards
• Pull request process
• Development workflow

📄 License

MIT License - see file for details

🆘 Support

• Issues: GitHub Issues
• Documentation: VTEX Developer Portal
• MCP Protocol: Model Context Protocol Docs

🎯 Roadmap

• Add response caching
• Implement rate limiting
• Add webhook support
• Create CLI for testing tools
• Add more detailed logging options
• Support for multiple VTEX accounts

⭐ Acknowledgments

• Built on the Model Context Protocol SDK
• VTEX API definitions from VTEX Developer Portal
• Inspired by the VTEX developer community

Made with ❤️ for the VTEX ecosystem