# Vtex Mcp Server

> VTEX MCP Server

- **Type:** MCP server
- **Install:** `agentstack add mcp-volve-tech-vtex-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Volve-Tech](https://agentstack.voostack.com/s/volve-tech)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Volve-Tech](https://github.com/Volve-Tech)
- **Source:** https://github.com/Volve-Tech/vtex-mcp-server

## Install

```sh
agentstack add mcp-volve-tech-vtex-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)

```bash
npm install -g vtex-mcp-server
```

### From source

```bash
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:

```env
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

```bash
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`

```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)

```json
{
  "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

```bash
npm run build
```

### Development Mode (watch)

```bash
npm run dev
```

### Regenerating Endpoints

If you update the Postman collection, regenerate the endpoints:

```bash
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 [CONTRIBUTING.md](CONTRIBUTING.md) for details on:
- Code style and standards
- Pull request process
- Development workflow

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/Volve-Tech/vtex-mcp-server/issues)
- **Documentation**: [VTEX Developer Portal](https://developers.vtex.com/)
- **MCP Protocol**: [Model Context Protocol Docs](https://modelcontextprotocol.io/)

## 🎯 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](https://github.com/modelcontextprotocol/sdk)
- VTEX API definitions from [VTEX Developer Portal](https://developers.vtex.com/)
- Inspired by the VTEX developer community

---

Made with ❤️ for the VTEX ecosystem

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Volve-Tech](https://github.com/Volve-Tech)
- **Source:** [Volve-Tech/vtex-mcp-server](https://github.com/Volve-Tech/vtex-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-volve-tech-vtex-mcp-server
- Seller: https://agentstack.voostack.com/s/volve-tech
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.