brmarket-mcp

brmarket-mcp

MCP server for Brazilian marketplace product search, paid automatically with x402 micropayments (USDC on Base or Solana).

One call searches Mercado Livre, Shopee and AliExpress together and returns a single normalized shape: BRL prices in integer cents, canonical + affiliate links, and a per-marketplace sources state so a degraded marketplace is never silent. A free import-tax calculator turns a price into the real landed price — the honest "best value with Brazilian import tax" comparison.

Status: brmarket-mcp@0.2.1. 0.2.0 is LIVE on npm and the MCP registry (verified against registry.npmjs.org, not against this file — an earlier "not published yet" line here was stale, and a doc is not evidence). 0.2.1 sends an Idempotency-Key derived from the request, so a retry by the calling agent replays the paid response for free instead of paying twice. 0.2.0 added AliExpress freight (shippingCents), ships-from origin and real landed prices, and corrected the claim that Mercado Livre pays no affiliate commission — it has since 2026-07-23. Publishing is a manual step (npm login required). See Publishing below.

Tools

Tool	Price	What it does
search_products	$0.01	Mercado Livre + Shopee + AliExpress in one call. Normalized BRL prices (integer cents), canonical + affiliate links, rating, sold count, seller id/name/official-store, dataAsOf. AliExpress offers add shippingCents (freight to Brazil), shipFromCountry and deliveryDaysMax, and cheapest-first orders on price + freight. ⚠️ Absent shippingCents = freight UNKNOWN, never free.
search_by_image	$0.05	Same, but from a product photo. Returns interpreted_query so you can see what was actually searched.
search_products_preview	free	One result, canonical link only, no affiliate link.
calculate_import_taxes	free	Brazilian import tax + landed price of a cross-border purchase (Import Tax 0% ≤ US$50 else 30% − US$20, ICMS por-dentro by state, Bacen PTAX rate). BRL cents or USD in; pass uf on search_products too for per-offer landed_price_estimate.

Always read sources

Every response reports each marketplace as ok / error / timeout / not_configured. A short result list may mean a marketplace was down, not that the market is thin. Never present a degraded page as the whole market.

Install

npx brmarket-mcp

Claude Desktop / Claude Code (claude_desktop_config.json):

{
  "mcpServers": {
    "brmarket": {
      "command": "npx",
      "args": ["-y", "brmarket-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0x…"
      }
    }
  }
}

The free preview tool works with no wallet at all.

Environment

Variable	Required	Description
EVM_PRIVATE_KEY	no	0x… key of a dedicated wallet holding USDC on Base.
SOLANA_PRIVATE_KEY	no	base58 or JSON-array secret key of a dedicated Solana wallet holding USDC.
SOLANA_RPC_URL	no	RPC override used to build the Solana payment (e.g. a Helius URL).
BRMARKET_BASE_URL	no	Defaults to https://brmarket.thomenz.me.
X402_NETWORK	no	base (default) or base-sepolia.

Configure either rail, or both — the x402 layer settles on whichever the server's 402 advertises. Without any key, paid tools fail with HTTP 402.

⚠️ These keys spend real money. Use dedicated wallets with small balances, never a personal or treasury key. Anything that can read this process' environment can spend from them.

Develop

npm install
npm run build          # tsc -> dist/
npm run typecheck
npm run version:check  # all FIVE version sites must agree

Publishing (manual — Thiago only)

npm run version:check   # wired into prepublishOnly too
npm publish

Then verify the tarball from the registry, not the local build:

npm pack brmarket-mcp@<version> --registry https://registry.npmjs.org
tar -xzOf brmarket-mcp-<version>.tgz package/dist/index.js | grep -o 'version: "[^"]*"'

A green build proves nothing about what was published — brdata-mcp 0.3.4 shipped from a stale source copy and its MCP handshake reported 0.3.2 while npm said 0.3.4. Check the tarball.

For the MCP registry, server.json carries the full environmentVariables block. Do not drop it: brdata-mcp 0.3.3 published without it and the registry entry lost every variable.

License

MIT © Thiago Menzinger