io.github.thomenz/brmarket-mcp
FREE Brazilian marketplace search (ML, Shopee, AliExpress) + import-tax calculator (x402)
Open source Open in the app JSON README (API)
About
FREE Brazilian marketplace search (ML, Shopee, AliExpress) + import-tax calculator (x402)
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- thomenz
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.0
- Last push
- 2026-07-18T19:53:17Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:01:32
- Updated
- 2026-09-07 17:15:35
- Origin id
io.github.thomenz/brmarket-mcp
README
# brmarket-mcp
MCP server for **Brazilian marketplace product search**, paid automatically with
[x402](https://x402.org) 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: not published yet.** `brmarket-mcp@0.1.0` is built and ready; publishing
> to npm and the MCP registry is a manual step. 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, free shipping, rating, sold count, seller id/name/official-store, `dataAsOf`. |
| `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
```bash
npx brmarket-mcp
```
Claude Desktop / Claude Code (`claude_desktop_config.json`):
```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
```bash
npm install
npm run build # tsc -> dist/
npm run typecheck
npm run version:check # all FIVE version sites must agree
```
## Publishing (manual — Thiago only)
```bash
npm run version:check # wired into prepublishOnly too
npm publish
```
Then verify **the tarball from the registry**, not the local build:
```bash
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