BrasilAPI (CNPJ, CEP, validation, holidays)

brasilapi-mcp

AI アシスタントに BrasilAPI を通じてブラジルの公開データを提供する MCP サーバーです。CNPJ による企業登録情報の照会（パートナーを含む）、CEP による住所の照会、オフラインでの CNPJ／CPF の検証、国民の祝日の確認ができます。

企業のデューデリジェンス（KYC）ワークフローの経験をもとに開発しました。このようなワークフローでは、エージェントが企業の実在と営業状況、パートナーを確認し、チェックディジット検証に失敗した番号を信頼しないことが求められます。これは独立したプロジェクトであり、BrasilAPI または Receita Federal とは提携していません。

ツール

ツール	機能	ネットワーク
lookup_cnpj	企業の正式名称、登録状況、主な事業、住所、規模、税制、パートナー（QSA）を確認します。句読点の有無を問わず、数字または英数字の CNPJ を受け付けます。	BrasilAPI
validate_cnpj	数字および英数字の CNPJ の形式とチェックディジットを確認します。	なし
validate_cpf	CPF の形式とチェックディジットを確認します。何も保存または送信しません。	なし
lookup_cep	CEP の通り、地区、市、州、IBGE コード、座標を確認します。	BrasilAPI
list_holidays	曜日を含む、ある年の国民の祝日を一覧表示します。	BrasilAPI

lookup_cnpj は、チェックディジットが正しくない番号をリクエストの前に拒否するため、入力ミスがあっても無駄な処理は発生せず、API に送信されることもありません。パートナーの CPF は登録機関によってマスキングされています（***123456**）。サーバーがマスキングを解除したり、情報を保存したりすることはありません。

include_partners: false を指定した lookup_cnpj の例：

{
  "cnpj": "00000000000191",
  "razaoSocial": "BANCO DO BRASIL SA",
  "situacaoCadastral": { "descricao": "ATIVA", "desde": "2005-11-03", "motivo": "SEM MOTIVO" },
  "tipo": "MATRIZ",
  "naturezaJuridica": "Sociedade de Economia Mista",
  "cnaePrincipal": { "codigo": 6422100, "descricao": "Bancos múltiplos, com carteira comercial" },
  "endereco": { "municipio": "BRASILIA", "uf": "DF", "cep": "70040912", "...": "..." },
  "totalSocios": 41
}

インストール

Node 20 以降が必要です。

Claude Code：

claude mcp add brasilapi -- npx -y @renatoctti/brasilapi-mcp

Claude Desktop、Cursor、および mcpServers ブロックを読み込むその他のクライアント：

{
  "mcpServers": {
    "brasilapi": {
      "command": "npx",
      "args": ["-y", "@renatoctti/brasilapi-mcp"]
    }
  }
}

ソースから：

git clone https://github.com/renatoctti/brasilapi-mcp
cd brasilapi-mcp
npm install
npm run build
node dist/src/index.js   # speaks MCP over stdio

補足

• データソース。 BrasilAPI は公開データを集約する無料のコミュニティサービスです。レート制限があり、サーバーは再試行せず、429 をわかりやすいメッセージで報告します。各リクエストには 10 秒のタイムアウトが設定されています。
• 識別情報。 BrasilAPI は、匿名のデフォルト HTTP エージェントからのリクエストを拒否するファイアウォールの背後にあるため、すべてのリクエストに User-Agent: brasilapi-mcp/<version> (+repo url) が付与されます。
• 英数字の CNPJ。 2026 年以降、Receita Federal は文字を含む CNPJ を発行しています。バリデーターは公開されているチェックディジットの規則（文字の値は ASCII コードから 48 を引いた値）に従います。照会で企業が見つかるかどうかは、BrasilAPI にその情報があるかによります。
• 最新性。 登録情報は Receita Federal のデータより数日遅れる場合があります。証明書ではなく、最初の確認手段として扱ってください。
• 状態を保持しません。 サーバーは呼び出し間で何も保持せず、照会した番号のログも記録しません。標準エラー出力に書き込まれるのは起動時の1行のみです。

開発

npm test        # builds, then runs the unit and protocol tests (no network)
npm run smoke   # starts the built server over stdio and calls every tool on the real API

テストでは、チェックディジットの規則（数字および英数字の CNPJ、CPF）、各応答の再構成、エラー処理（見つからない場合、レート制限、接続不能）、および BrasilAPI の代わりに偽の fetch を使用した、インメモリ MCP クライアント経由でのサーバー自体を検証します。

ライセンス

MIT