io.github.thomenz/brdata-mcp

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

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:

⚠️ 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:

{
  "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:

{
  "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

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