io.github.thomenz/brdata-mcp
Brazilian company, risk & public-tender data (CNPJ, CEIS/CNEP, PNCP) as x402-paid agent tools
Open source Open in the app JSON README (API)
About
Brazilian company, risk & public-tender data (CNPJ, CEIS/CNEP, PNCP) as x402-paid agent tools
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- thomenz
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.7
- Last push
- 2026-08-04T12:43:26Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:01:32
- Updated
- 2026-08-29 04:01:32
- Origin id
io.github.thomenz/brdata-mcp
README
# brdata-mcp
An **MCP (Model Context Protocol) server** for **Brazilian company & public-procurement
data**, for agent harnesses (Claude Code, Claude Desktop, …). It covers: CNPJ company
registry lookup (basic + full due-diligence), **company search/discovery** across ~28M
active companies by filters (CNAE activity, state/city, size, MEI, name), **public tenders
/ licitações via PNCP** (decode Compras.gov.br IDs, resolve, header, line items, edital
documents, keyword search), NF-e & boleto decoding, CEP lookup, and batch document
validation — for KYB, due diligence, and B2G (public-sector) sales intelligence.
Paid tools **automatically settle** the underlying x402-protected HTTP endpoints in **USDC
on Base or Solana** using a wallet you configure; a call is charged only on success. Configure a
Base wallet (`EVM_PRIVATE_KEY`), a Solana wallet (`SOLANA_PRIVATE_KEY`), or both — the x402 layer
settles on whichever rail the server's 402 challenge advertises.
## Tools
| Tool | Endpoint | Price | Description |
|------|----------|-------|-------------|
| `lookup_company` | `GET /company/{cnpj}` | $0.005 | Consolidated registry profile |
| `lookup_company_full` | `GET /company/{cnpj}/full` | $0.03 | + partners (QSA) + sanctions |
| `screen_company_risk` | `GET /risk/company/{cnpj}` | $0.015 | Regulatory risk & compliance screen across 5 federal registries: debarment (CEIS), anti-corruption (CNEP), impeded non-profits (CEPIM), leniency & forced-labor register ("Lista Suja", MTE) → verdict + 0–100 score + per-source `data_as_of` |
| `decode_nfe_key` | `GET /nfe/{key}` | $0.005 | NF-e/NFC-e 44-digit access-key decoder |
| `decode_boleto` | `POST /boleto/decode` | $0.005 | Boleto digitable-line decoder |
| `validate_documents` | `POST /validate/batch` | $0.001 | Batch validate CPF/CNPJ/PIS/plate/Pix (≤100) |
| `lookup_cep` | `GET /cep/{cep}` | $0.002 | Enriched postal-code lookup |
| `search_companies` | `POST /companies/search` | $0.015/page | Search & segment active companies by CNAE/location/size/age/name |
| `decode_tender_id` | `GET /tender/decode/{id}` | $0.005 | Offline decode of a Compras.gov.br 17-digit tender id |
| `resolve_tender` | `POST /tender/resolve` | $0.02 | Resolve any tender reference (id/URL/control number) to PNCP + summary |
| `get_tender` | `GET /tender/{cnpj}/{year}/{seq}` | $0.01 | Full tender header (PNCP) |
| `get_tender_items` | `GET /tender/{cnpj}/{year}/{seq}/items` | $0.03 | All tender items + ME/EPP-exclusive flags |
| `get_tender_documents` | `GET /tender/{cnpj}/{year}/{seq}/documents` | $0.01 | Tender document URIs (no PDF download) |
| `search_tenders` | `POST /tender/search` | $0.05 | Search public tenders (PNCP) by keyword |
| `validate_cnpj` | `GET /validate/{cnpj}` | **free** | Single CNPJ check-digit validation |
`search_companies` requires the Worker to have the Phase 2 database configured (Hyperdrive);
otherwise it returns a 503 (and no payment is charged). MEI contact data is redacted (LGPD).
## Configuration
Environment variables:
| Var | Required | Default | Meaning |
|-----|----------|---------|---------|
| `BRDATA_BASE_URL` | no | `https://brdata.thomenz.me` | Base URL of a brdata Worker (defaults to the hosted production API) |
| `EVM_PRIVATE_KEY` | for paid tools (Base) | — | `0x`-prefixed key of the paying Base wallet (holds USDC) |
| `SOLANA_PRIVATE_KEY` | for paid tools (Solana) | — | base58 or JSON-array secret key of the paying Solana wallet (holds USDC). Configure this and/or `EVM_PRIVATE_KEY` |
| `SOLANA_RPC_URL` | no | public RPC | Optional Solana RPC override used to build the payment (e.g. a Helius URL) |
| `X402_NETWORK` | no | `base` | `base` (mainnet, matches the default URL) or `base-sepolia` (testnet → Solana devnet) |
## ⚠️ Security
`EVM_PRIVATE_KEY` controls **real funds**. Anything that can read this process'
environment (or the MCP config file) can spend from that wallet.
- Use a **dedicated wallet with a small balance**, funded only with what you're
willing to auto-spend. Never a personal or treasury key.
- On testnet (`base-sepolia`) use test USDC only.
- The key is read from the environment; it is never sent anywhere except to sign
x402 payment authorizations for `BRDATA_BASE_URL`.
## Use with Claude Code / Claude Desktop
Add to your `mcpServers` configuration:
```json
{
"mcpServers": {
"brdata": {
"command": "npx",
"args": ["-y", "brdata-mcp"],
"env": {
"EVM_PRIVATE_KEY": "0x<dedicated-wallet-key-with-USDC>"
}
}
}
}
```
For local development against `wrangler dev`, point `BRDATA_BASE_URL` at
`http://localhost:8787` and use `X402_NETWORK=base-sepolia` with a testnet wallet.
If you run from source instead of npm, use:
```json
{
"mcpServers": {
"brdata": {
"command": "node",
"args": ["/absolute/path/to/packages/brdata-mcp/dist/index.js"],
"env": { "BRDATA_BASE_URL": "http://localhost:8787", "EVM_PRIVATE_KEY": "0x...", "X402_NETWORK": "base-sepolia" }
}
}
}
```
## Example
> "Use brdata to run full due diligence on CNPJ 00.000.000/0001-91."
The agent calls `lookup_company_full`, which pays $0.03 in USDC and returns the
consolidated English profile with partners and sanction checks.
## Build & publish
```bash
pnpm install
pnpm run build # emits dist/
pnpm run typecheck
# publish (see checklist in the main repo README before doing this):
npm publish --access public
```
## License
MIT