# io.github.codespar/mcp-vtex (npm · @codespar/mcp-vtex)

MCP server for VTEX — e-commerce, orders, products, inventory, shipping

- Trust score: 68/100 (medium)
- Change this week: +22
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@codespar/mcp-vtex`: 68/100 (this document), [markdown](https://verifymcp.io/servers/codespar-mcp-vtex/codespar-mcp-vtex.md), [page](https://verifymcp.io/servers/codespar-mcp-vtex/codespar-mcp-vtex)

## Channel facts

- Registry: `npm`
- Package: `@codespar/mcp-vtex`
- Version: `0.2.2`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 86/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 41 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 70/100
  - AI-judged instruction clarity (good).
  - Tool/resource definitions use about 2333 tokens (~70/item across 33 items; 33 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add codespar-mcp-vtex -- npx -y @codespar/mcp-vtex
```

### Codex

```bash
codex mcp add codespar-mcp-vtex -- npx -y @codespar/mcp-vtex
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codespar-mcp-vtex": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@codespar/mcp-vtex"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add codespar-mcp-vtex --command npx --arg -y --arg @codespar/mcp-vtex
```

### Hermes

```yaml
mcp_servers:
  codespar-mcp-vtex:
    command: "npx"
    args: ["-y", "@codespar/mcp-vtex"]
```

### Other

```json
{
  "mcpServers": {
    "codespar-mcp-vtex": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-vtex"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-02 (score 67, +46)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [functional improvement] License: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Stability: unverified → 0.23
- [functional improvement] Schema quality: unverified → good
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional] Licence: MIT

### 2026-07-31 (score 21, −25)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-27 (score 46)

First indexed and scored.

## MCP tools (33)

### `list_products` (~53 tokens)

List products from VTEX catalog

Input parameters:

- `categoryId` (number): Filter by category ID
- `from` (number): Start index (default 1)
- `to` (number): End index (default 10)

### `get_product` (~24 tokens)

Get product details by ID

Input parameters:

- `productId` (number, required): Product ID

### `create_product` (~129 tokens)

Create a new product in the VTEX catalog

Input parameters:

- `BrandId` (number, required): Brand ID
- `CategoryId` (number, required): Category ID
- `Description` (string): Product description (HTML supported)
- `DescriptionShort` (string): Short description
- `IsActive` (boolean): Active status (default true)
- `IsVisible` (boolean): Product visibility (default true)
- `LinkId` (string): URL slug
- `Name` (string, required): Product name
- `RefId` (string): Reference ID (internal code)
- `Title` (string): Page title (SEO)

### `update_product` (~88 tokens)

Update an existing product in the VTEX catalog

Input parameters:

- `BrandId` (number): Brand ID
- `CategoryId` (number): Category ID
- `Description` (string): Product description
- `IsActive` (boolean): Active status
- `IsVisible` (boolean): Product visibility
- `Name` (string): Product name
- `productId` (number, required): Product ID to update

### `list_skus` (~26 tokens)

List SKUs for a product

Input parameters:

- `productId` (number, required): Product ID

### `create_sku` (~117 tokens)

Create a new SKU for a product

Input parameters:

- `IsActive` (boolean): Active status
- `Name` (string, required): SKU name
- `PackagedHeight` (number): Packaged height in cm
- `PackagedLength` (number): Packaged length in cm
- `PackagedWeightKg` (number): Packaged weight in kg
- `PackagedWidth` (number): Packaged width in cm
- `ProductId` (number, required): Parent product ID
- `RefId` (string): Reference ID (internal code)

### `list_categories` (~40 tokens)

List all categories with pagination

Input parameters:

- `from` (number): Start index (default 1)
- `to` (number): End index (default 10)

### `create_category` (~100 tokens)

Create a new category in the catalog

Input parameters:

- `Description` (string): Category description
- `FatherCategoryId` (number): Parent category ID (null for root)
- `IsActive` (boolean): Active status (default true)
- `Keywords` (string): SEO keywords (comma-separated)
- `Name` (string, required): Category name
- `ShowInStoreFront` (boolean): Show in store navigation
- `Title` (string): Page title (SEO)

### `get_catalog` (~30 tokens)

Get the catalog category tree

Input parameters:

- `levels` (number): Number of category tree levels (default 3)

### `list_orders` (~131 tokens)

List orders with optional filters

Input parameters:

- `f_creationDate` (string): Date range filter (e.g., creationDate:[2024-01-01T00:00:00.000Z TO 2024-12-31T23:59:59.999Z])
- `page` (number): Page number (default 1)
- `per_page` (number): Items per page (default 15)
- `q` (string): Search query (order ID, customer name, email)
- `status` (string): Filter by status (e.g., ready-for-handling, payment-approved)

### `get_order` (~26 tokens)

Get full OMS order details by ID

Input parameters:

- `orderId` (string, required): Order ID

### `update_order_status` (~30 tokens)

Transition an order to the handling state (start fulfillment)

Input parameters:

- `orderId` (string, required): Order ID

### `invoice_order` (~164 tokens)

Issue a fiscal invoice (nota fiscal) for an order

Input parameters:

- `courier` (string): Shipping carrier name
- `invoiceKey` (string): Fiscal key (chave da NFe)
- `invoiceNumber` (string, required): Invoice number issued by the ERP
- `invoiceUrl` (string): URL to the invoice PDF/XML
- `invoiceValue` (number, required): Invoice total value in cents
- `issuanceDate` (string, required): Issuance date in ISO 8601 format
- `items` (array, required): Items in the invoice
- `orderId` (string, required): Order ID
- `trackingNumber` (string): Tracking number
- `trackingUrl` (string): Tracking URL
- `type` (string, required): Invoice type: Output (sale) or Input (return)

### `track_order_invoice` (~67 tokens)

Update tracking info for a previously issued invoice

Input parameters:

- `courier` (string): Carrier name
- `invoiceNumber` (string, required): Invoice number
- `orderId` (string, required): Order ID
- `trackingNumber` (string, required): Tracking number
- `trackingUrl` (string): Tracking URL

### `cancel_order` (~32 tokens)

Cancel an order

Input parameters:

- `orderId` (string, required): Order ID
- `reason` (string): Reason for cancellation

### `list_customer_orders` (~64 tokens)

List order history for a customer (filtered by email)

Input parameters:

- `clientEmail` (string, required): Customer email
- `page` (number): Page number (default 1)
- `per_page` (number): Items per page
- `status` (string): Filter by status

### `get_sku_price` (~45 tokens)

Get pricing details for an SKU (base price, list price, markup, cost, fixed prices per trade policy)

Input parameters:

- `itemId` (string, required): SKU / item ID

### `update_sku_price` (~79 tokens)

Update base/list/cost price for an SKU

Input parameters:

- `basePrice` (number): Selling base price
- `costPrice` (number): Cost price
- `itemId` (string, required): SKU / item ID
- `listPrice` (number): Suggested selling (crossed-out) price
- `markup` (number): Markup percentage

### `list_price_tables` (~18 tokens)

List all configured price tables (trade policies)

### `get_inventory` (~28 tokens)

Get inventory/stock for a SKU across warehouses

Input parameters:

- `skuId` (number, required): SKU ID

### `update_inventory` (~62 tokens)

Update inventory quantity for a SKU at a specific warehouse

Input parameters:

- `quantity` (number, required): New quantity
- `skuId` (number, required): SKU ID
- `unlimitedQuantity` (boolean): Set unlimited quantity (default false)
- `warehouseId` (string, required): Warehouse ID

### `get_shipping_rates` (~55 tokens)

Simulate shipping rates for items to a postal code

Input parameters:

- `country` (string): Country code (default BRA)
- `items` (array, required): Items to simulate
- `postalCode` (string, required): Destination postal code (CEP)

### `list_warehouses` (~18 tokens)

List all warehouses configured in the account

### `create_warehouse` (~88 tokens)

Register a new warehouse (fulfillment center)

Input parameters:

- `id` (string, required): Warehouse ID (slug, unique)
- `isActive` (boolean): Active (default true)
- `name` (string, required): Warehouse display name
- `priority` (number): Priority among warehouses (lower = higher priority)
- `warehouseDocks` (array): Docks (shipping origin points) attached to this warehouse

### `create_promotion` (~105 tokens)

Create a promotion/discount in VTEX

Input parameters:

- `beginDateUtc` (string, required): Start date (ISO 8601)
- `endDateUtc` (string, required): End date (ISO 8601)
- `isActive` (boolean): Active status
- `name` (string, required): Promotion name
- `nominalDiscountValue` (number): Fixed discount amount
- `percentualDiscountValue` (number): Percentage discount (0-100)
- `type` (string, required): Promotion type

### `list_coupons` (~15 tokens)

List all promotion coupons

### `create_coupon` (~99 tokens)

Create a promotion coupon code

Input parameters:

- `expirationIntervalPerUse` (string): Time between uses (ISO 8601 duration)
- `isArchived` (boolean): Archived state (default false)
- `maxItemsPerClient` (number): Max usage per customer (0 = unlimited)
- `promotionId` (string, required): Promotion ID this coupon is tied to
- `utmSource` (string, required): Coupon code / UTM source (what the customer types)

### `list_subscriptions` (~59 tokens)

List customer subscriptions

Input parameters:

- `page` (number): Page number (default 1)
- `perPage` (number): Items per page
- `status` (string): Filter by status (ACTIVE, PAUSED, CANCELED, EXPIRED)

### `create_subscription` (~121 tokens)

Create a recurring subscription for a customer (VTEX Subscriptions)

Input parameters:

- `customerEmail` (string, required): Customer email
- `items` (array, required): Items in the subscription (skuId + quantity)
- `nextPurchaseDate` (string): ISO 8601 datetime of next purchase
- `plan` (object, required): Plan / frequency settings
- `purchaseSettings` (object, required): Purchase settings (currencyCode, paymentMethod, etc.)
- `shippingAddress` (object, required): Shipping address. Must include addressId or full address fields.
- `title` (string): Subscription title

### `get_masterdata_document` (~72 tokens)

Get a document (customer profile, custom entity) from VTEX Master Data v2

Input parameters:

- `dataEntity` (string, required): Data entity name (e.g., CL for clients)
- `fields` (string): Comma-separated fields to return (default: all)
- `id` (string, required): Document ID

### `search_masterdata` (~97 tokens)

Search documents in a Master Data entity

Input parameters:

- `dataEntity` (string, required): Data entity name (e.g., CL for clients)
- `fields` (string, required): Comma-separated fields (required by VTEX)
- `rangeEnd` (number): Pagination end (default 10)
- `rangeStart` (number): Pagination start (default 0)
- `where` (string): Filter expression (e.g., email=customer@example.com)

### `create_giftcard` (~155 tokens)

Create a gift card for a customer (GiftCard Hub)

Input parameters:

- `caption` (string, required): Short description of the gift card
- `discount` (boolean): Whether the gift card is a discount (default false)
- `expiringDate` (string, required): Expiration date in ISO 8601 format
- `multipleCredits` (boolean): Allow multiple credits (default true)
- `multipleRedemptions` (boolean): Allow multiple redemptions (default true)
- `profileId` (string, required): Customer profile ID (email or client ID)
- `relationName` (string, required): Unique identifier for client-gift card relationship (UUID recommended)
- `restrictedToOwner` (boolean): Restrict redemption to the owner (default false)

### `get_giftcard` (~29 tokens)

Get gift card details by ID

Input parameters:

- `giftCardId` (string, required): Gift card ID

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/codespar-mcp-vtex/codespar-mcp-vtex#diagnostics

## Score history

- 2026-08-03: 68
- 2026-08-02: 67
- 2026-08-01: 21
- 2026-07-31: 21
- 2026-07-30: 46
- 2026-07-28: 46
- 2026-07-27: 46

## Links

- npm package: https://www.npmjs.com/package/@codespar/mcp-vtex
- Socket report: https://socket.dev/npm/package/@codespar/mcp-vtex
- Repository: https://github.com/codespar/mcp-dev-latam
- Changelog RSS feed: https://verifymcp.io/servers/codespar-mcp-vtex/codespar-mcp-vtex/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/codespar-mcp-vtex/codespar-mcp-vtex/changelog.json
- HTML version of this page: https://verifymcp.io/servers/codespar-mcp-vtex/codespar-mcp-vtex