vtex-account-mcp-server

Read-only MCP server for inspecting a live VTEX account's configuration. Used by the vtex-inspector skill in the AI Atlas Claude plugin.

Authentication

This server authenticates using the VTEX CLI session — no API keys needed.

Every tool accepts an account parameter (the VTEX account name, e.g. mystore). The token for that account is read on every call from:

~/.vtex/session/tokens.json   →  { accountName: jwtToken, ... }

The token is sent as the VtexIdclientAutCookie header on every request, exactly as the VTEX CLI does. Token reads happen on every tool call, so refreshes are picked up automatically.

Before calling a tool for an account, make sure you are logged in:

vtex login <account-name>

Tools

| Tool | Domain | Returns | |------|--------|---------| | vtex_get_account_info | Account | Company name, stores, appTokens | | vtex_get_stores | Account | Store bindings and hostnames | | vtex_get_warehouses | Logistics | All warehouses with docks and hours | | vtex_get_docks | Logistics | All docks with carriers and processing time | | vtex_get_shipping_policies | Logistics | Carriers and SLAs | | vtex_get_pickup_points | Logistics | Pickup points with address and hours | | vtex_get_delivery_capacity | Logistics | Scheduled window capacity per carrier | | vtex_get_category_tree | Catalog | Department → category hierarchy | | vtex_get_brands | Catalog | All brands with active status | | vtex_get_sales_channels | Catalog | Trade policies / sales channels | | vtex_get_catalog_summary | Catalog | Product and SKU count (paginated) | | vtex_get_promotions | Promotions | All promotions with type and conditions | | vtex_get_price_tables | Pricing | Price tables with rules | | vtex_get_coupons | Promotions | Active coupons with usage stats | | vtex_get_price_table_mapping | Pricing | Audience → price table mapping | | vtex_get_payment_affiliations | Payments | Connected gateway connectors | | vtex_get_payment_rules | Payments | Payment conditions per method | | vtex_get_installments | Payments | Installment options | | vtex_get_orderform_config | Checkout | orderForm config and custom apps | | vtex_get_affiliates | Integrations | Connected marketplaces | | vtex_get_order_hook_config | Integrations | OMS webhook configuration | | vtex_get_subscription_settings | Subscriptions | Global subscription feature config | | vtex_get_subscription_plans | Subscriptions | Subscription plans and frequencies |

Requirements

• Node.js 18+
• VTEX CLI installed and logged in

Installation

npm install -g @miguel-carrera/vtex-account-mcp-server

Or use directly with npx (no install needed):

npx @miguel-carrera/vtex-account-mcp-server

Add to Claude (.mcp.json)

{
  "mcpServers": {
    "vtex-account": {
      "command": "npx",
      "args": ["-y", "@miguel-carrera/vtex-account-mcp-server"]
    }
  }
}

No credentials in the config — the server reads them from the VTEX CLI session.

Development

git clone https://github.com/miguel-carrera/vtex-account-mcp-server.git
cd vtex-account-mcp-server
npm install

# Watch mode (no build step needed)
npm run dev

# Rebuild after changes
npm run build