Brazil CNPJ company registry

cnpj-mcp

ブラジルの公開企業登記簿（CNPJ）に関する分析的な質問に対応する MCP サーバーです。Receita Federal の月次オープンデータダンプを基に構築されています。単一の番号を検索するのではなく、多数の企業を対象とした質問向けです。

• 2023年以降、ミナスジェライス州では毎月いくつの MEI が設立されましたか？
• マットグロッソ州で、活動中の大豆・穀物関連企業が最も多い自治体はどこですか？
• 同じ住所を共有している企業と、そのパートナーは誰ですか？
• 毎年いくつの企業が閉鎖し、その理由は何ですか？

単一の CNPJ の検索もできますが、その用途には無料の API がすでに十分対応しています。

含まれるデータ

Receita のダンプに含まれるすべての事業所、企業、パートナー、Simples/MEI のレコードを結合し、高速なクエリ向けに型を整えています。値は Receita の公開どおり、ポルトガル語のままです。読み込まれたスナップショットの月と行数については、dataset_info を参照してください。

Receita のファイル	行の内容
Estabelecimentos + Empresas + Simples	CNPJ ごと（matriz および filiais）に1行。企業、規模、資本金、法的形態、MEI/Simples のフラグ、CNAE、住所、連絡先を含みます
Socios	パートナーとの関係ごとに1行。氏名を含みます（CPF は Receita によってマスキングされています）
Cnaes, Municipios, Naturezas, Motivos, Paises, Qualificacoes	コードテーブル

出典：Receita Federal、Dados Abertos CNPJ、https://www.gov.br/receitafederal/pt-br/acesso-a-informacao/dados-abertos/cadastros

使い方

ホスト型エンドポイント（ストリーミング可能な HTTP）：MCP レジストリに io.github.bnovarini/cnpj-mcp として掲載されています。

または、自分で実行します。

pip install "cnpj-mcp[ingest]"
cnpj-mcp ingest 2026-09 ./raw          # streams Receita's zips straight to Parquet, about 7 GB downloaded
cnpj-mcp build 2026-09 ./raw ./data    # joins and types them
CNPJ_DATA_DIR=./data cnpj-mcp          # MCP server over stdio

ingest の実行には、PATH 上に curl と unzip が必要です。zip ファイルや CSV をディスクに書き込むことはなく、ディスク使用量は Parquet 出力分のみです（約 8 GB）。処理済みのファイルはスキップするため、中断後に再実行できます。ビルド手順では、ソートとスワップ用に約 20 GB の空き容量が必要です。

ツール：dataset_info、search_companies、count_companies、get_company、list_partners、search_partners、companies_at_address、lookup_codes。

連絡先の品質スコア

get_company と search_companies（include_contacts を指定した場合）は、registry_contact_quality ブロックを返します。これには 0～100 の contact_score、ティア（高：85以上、中：50～84、低：50未満）、およびその根拠となるシグナルが含まれます。このスコアは、Receita に登録されたメールアドレスまたは電話番号が、実際の直接連絡先である可能性を推定します。誰かが応答するかどうかを確認するものではありません。

シグナルは、すべて Receita のダンプ自体から算出されます。

• メールアドレスの種類：企業ドメイン、無料プロバイダー（gmail、hotmail、uol など）、会計事務所のようなアドレス、入力ミスのある無料プロバイダー（gmial.com など）、または無効なアドレス。
• 同じメールアドレスを共有する企業数と、同じメールドメインを使用する企業数。1社のみであれば良い兆候ですが、数十社が共有している場合は、通常、会計事務所または共有メールボックスです。
• メールアドレスが企業名と一致するかどうか。
• 電話の種類（携帯電話または固定電話。Receita では、携帯電話が9桁目を含めずに登録されていることがよくあります）と、同じ電話番号を共有する企業数。

contact_score は、メールアドレスと電話番号のスコアのうち高い方です。search_companies の min_contact_score には、0～100 の整数またはティア名（low = 0、medium = 50、high = 85）を指定できます。指定した値以上の登録連絡先スコアを持つ企業のみが残ります。ウェブサイトについては何も示しません。ページを読み込んだ後にフィルタリングするため、1回の呼び出しで確認する候補は最大2000件です。続きは pagination.next_offset で取得できます。毎月のビルド後に python -m cnpj_mcp.scores <data_dir> で再構築してください。

企業ウェブサイトの連絡先（独立したブロックとして提供）

python -m cnpj_mcp.crawl domains.tsv out.jsonl は、法人のメールドメインのウェブサイトを巡回し、企業自身が公開している情報を記録します。WhatsApp のリンク、電話番号、メールアドレス、ソーシャルプロフィールを、それぞれの情報が掲載されていたページとともに記録します。robots.txt に従い、cnpj-mcp-crawler/0.1 と名乗り、ドメインごとに最大 1 秒に 1 回リクエストし、ホームページと連絡先ページを合わせて最大 1 ページずつ読み込みます。Cookie は保存しません。

サーバーは結果を website_contacts.parquet（ドメインごとに 1 行）から読み込み、get_company と include_contacts を指定した search_companies に、「企業自身のウェブサイトからの情報」とラベル付けした独立の website_contacts ブロックを追加します。サイトは企業の登録メールアドレスのドメインから特定され、各ブロックには企業ごとの match レベルと match_basis、note が含まれます。レベルは、confirmed（ページに CNPJ またはその 8 桁のルート番号が記載されている、もしくは企業名と登録済みの CEP、電話番号、市区町村のいずれかが記載されている）、likely（ページタイトル、見出し、著作権表示のいずれかに企業名のみが含まれている）、candidate（ページ上にサイトと企業を結び付ける情報がない）です。レベルは python -m cnpj_mcp.crawl によって判定され（ident.py を参照）、website_ident.parquet から提供されます。このブロックは Receita の項目とは分けてあり、contact_score には含まれません。

サイト所有者との照合、2026 年 10 月：連絡先情報がある 306,683 ドメインを再度クロールし、301,602 件の読み込みに成功しました。357,489 件の企業とサイトの組み合わせのうち、89,171 件（25％）が confirmed、34,421 件（10％）が likely、233,897 件（65％）が candidate でした。

初回調査、2026 年 10 月：1～3 社が使用する法人ドメインは 724,996 件でした。420,058 件のサイトを読み込みました（57.9％）。クリーニング後、414,185 件のサイトで利用可能な連絡先が見つかり、4,004 件はパーキング中、または「サイトが利用できません」というページ（例：static.uni5.net/indisponivel.php）であることが判明しました。また、1,869 件はソーシャルページまたはログインページにリダイレクトされており、連絡先情報は返されません。利用可能な 414,185 件のサイトのうち、WhatsApp リンクが掲載されているサイトは 40％、電話番号は 55％、メールアドレスは 54％、ソーシャルプロフィールは 51％でした。WhatsApp、電話番号、メールアドレスのいずれかが掲載されているサイトは 70％です。残りはアクセス不能（DNS または接続なしが 28％）、エラーページを返した、または robots.txt でボットのアクセスが拒否されていたためスキップされました（3.9％）。

クリーニング（python -m cnpj_mcp.postprocess merged.jsonl out.parquet。クローラーの処理にも適用）：電話番号と WhatsApp の番号は、有効なブラジルの番号である必要があります（実在する市外局番、携帯電話は 9 桁、固定電話は 8 桁で、同じ数字や連続する数字だけの番号ではないこと）。先頭に余分に付いたゼロと 55 のプレフィックスは正規化し、古い 8 桁の携帯電話番号には WhatsApp 用に 9 桁目を追加し、国外の番号は除外します。プレースホルダーのメールアドレスとエラートラッカーのメールアドレスは削除します。汎用的なソーシャルパス（profile.php、sharer.php、reel など）と、異なる 10 以上のドメインで見つかった情報（ソーシャル）、または 25 以上のドメインで見つかった情報（電話番号、WhatsApp、メールアドレス）は削除します。これらはウェブサイトビルダー、ホスト、プラットフォームに属するためです。サイトは candidate マッチにすぎません。登録メールアドレスのドメインから特定されるため、ブロックには "match": "candidate" が含まれます。更新するには、新しいドメインリストでクロールを再実行してください。

数値を引用する前にお読みください

• 登記情報には現在の状態のみが表示されます。企業の過去の所在地、事業内容、資本金は記録されていません。
• レコードの約半数は閉鎖済みです（situacao baixada）。営業中の企業を対象にする場合は situacao で絞り込んでください。
• 件数は施設単位（CNPJ ごとに 1 件）です。unit='empresas' を指定すると、企業単位（matriz のみ）の件数になります。
• Capital social は企業が申告した BRL 建ての金額です。実際の資産を示すものではありません。
• Receita のデータの精度は、企業や登記機関が報告する情報の精度に依存します。開業日、CNAE コード、住所は誤っている場合や古い場合があります。
• MEI と Simples のフラグには現在の選択状況が表示され、開始日または終了日も示されます。

個人データとLGPD

Receitaは提携先の名前を公開しており、このプロジェクトにも含まれています。公開情報であっても、LGPDの下では個人データに該当します。

• Receitaは公開前にCPFをマスキングしており（中央の6桁のみ表示）、このプロジェクトでもマスキングした状態を維持しています。そこから個人を再特定しようとしないでください。
• 名前だけでは、別人が一致する場合があります。名前の一致を、2つのレコードが同一人物である証拠として扱わないでください。
• 提携先の検索は、デューデリジェンス、ジャーナリズム、調査研究など、正当な目的で利用してください。人物のプロファイリング、嫌がらせ、迷惑マーケティングには使用しないでください。
• 連絡先（メールアドレス、電話番号）もReceitaによって公開されています。include_contactsを指定して要求した場合にのみ返されます。

照合

件数は、ソースおよび政府独自の数値と照合されています。一致しない数値とその理由を含め、docs/AUDIT.mdを参照してください。

ライセンス

コードはMITライセンスです。データはReceita Federalのオープンデータプログラムに由来します。再利用に関するReceitaの最新の利用条件を確認してください。

レスポンス形式

search_companiesとsearch_partnersは、{"companies" | "partners": [...], "pagination": {"has_more", "next_offset", "returned"}, "message"?}を返します。ページには常にデータ行のみが含まれます。次の呼び出しでは、pagination.next_offsetをoffsetとして使用してください。

使用状況のログ記録

ホスト型サーバーは、個人データやクエリ内容を含まない簡易的な使用状況ログを保持します。初期化とツール呼び出しごとに、UTCタイムスタンプ、イベント、ツール名、およびクライアントがMCP初期化ハンドシェイクで送信するクライアント名とバージョンを記録します。IPアドレス、引数、結果は保存されません。同じマシン上のSQLiteテーブル（/data/usage.db）に保存されます。無効にするには、CNPJ_USAGE_LOG=0を設定してください。

マシンから統計情報を読み取ります（数値は日数のウィンドウを示し、既定値は30です）。

fly ssh console -a cnpj-mcp -C "python -m cnpj_mcp.usage 30"

クエリの安全性

ホスト型クエリでは、既定で上限付きのワーカーを1つ使用し、リクエストのクエリ予算を10秒（CNPJ_QUERY_TIMEOUT）に設定しています。負荷の高いリクエストが同時に発生した場合、上限のないキューに追加する代わりに、再試行を促すメッセージを返します。ヘルスチェックとデータセットのメタデータは引き続き応答可能です。中断されたクエリは部分的な結果ではなく、エラーを返します。

会社名の部分文字列フィルターでは、ufの指定と3～256文字の入力が必要です。提携先の部分文字列検索でもufの指定が必要で、既存の最小名前長が維持されます。全国を対象とした部分文字列による名前検索には対応していません。タイムアウトした場合は、州、業種、または日付範囲で絞り込んでください。新しいインデックス、サイドカー、非公開のスキャン上限はありません。

オプションのPostHogオブザーバビリティ

HTTPサーバーでは、サーバーのシークレットストアにCNPJ_POSTHOG_TOKENを設定すると、リクエスト単位のツールスパンと、サニタイズされたエラーイベントをエクスポートできます。 トークンが設定されていない場合、エクスポートは行われません。 CNPJ_POSTHOG_HOSTの既定値はhttps://us.i.posthog.comです。EUのプロジェクトでは https://eu.i.posthog.comを使用できます。プロジェクトトークンをソースや設定ファイルに含めないでください。

エクスポートされるのは、ツール名、ステータス、所要時間、および既知のクライアント名／バージョンのみです。 エラーイベントにはSDKが生成した匿名IDが保持されますが、人物プロファイルは作成されません。引数、フィルター値、クエリテキスト、結果、呼び出し元のIPアドレス／User-Agent、セッション、生の例外メッセージ、スタックトレース、ローカル変数はエクスポートされません。 エラーには組み込みの型またはToolErrorと固定メッセージが使用されます。ハンドシェイクとヘルスチェックはエクスポートされません。一括呼び出しでは、リクエストの所要時間とステータスが共有されます。 クライアント名／バージョンはクライアントが提供するサニタイズ済みのラベルであり、検証済みのIDではありません。 PostHogには、引き続きトランスポートレベルでサーバーの外向きIPアドレスとSDKのUser-Agentが見えます。

エクスポーターでは、上限付きの非同期キューを使用します。正常なASGIシャットダウン時には最終フラッシュを試みますが、突然の終了やネットワーク障害によりテレメトリが失われる可能性があります。既存のSQLite使用状況ログは独立して動作します。エクスポートの失敗によってツールのレスポンスが変わることはありません。広範な自動計装や例外の自動捕捉は有効になっていません。

ゼロコストの上限を頼りにする前に、製品の請求上限を設定し、確認してください。取り込み時にHTTP 200が返っても、イベントがプロジェクトのUIに表示されるとは限りません。設定後、合成データを使用した安全なリクエストで、トレースとエラートラッキングの両方が機能することを確認してください。 オフラインの SDK ワイヤープライバシーと応答の透明性を確認するには、pytest tests/test_observability.py を実行してください。同じテストデータセットを CNPJ_DATA_DIR で指定したうえで、tests/compare_http_responses.py CHECKOUT [enabled] を実行すると、8 つすべての HTTP ツール応答のスナップショットを取得できます。省略可能な enabled 引数はダミーの認証情報と傍受されたネットワークトランスポートを使用し、テレメトリーは送信しません。

構造化ログのエクスポートは、オプションで CNPJ_POSTHOG_LOGS=1 によって別途有効にできます。同じシークレットとリージョンを使用し、/i/v1/logs に OTLP/protobuf を送信します。固定のツール完了／失敗メッセージ、重大度、タイムスタンプ、同じ許可リストに登録されたツールメタデータのみが出力されます。ルートハンドラーはインストールされないため、uvicorn アクセスログ、DuckDB ログ、任意の Python ログメッセージはすべて除外されます。暗黙的なトレース／ユーザー／セッションのコンテキストや、ホスト／プロセスのリソース検出は使用されません。ログのキューには上限があり、正常なシャットダウン時にフラッシュされます。ログのエクスポートが失敗しても、既存のトレース／エラーのエクスポートは無効になりません。

ログ／トレースは無料の取り込み枠を共有するため、有効にする前にログの課金上限を確認してください。意図的に保持料金を受け入れる場合を除き、デフォルトの保持期間を維持してください。保持料金は取り込みの課金上限の対象外です。

ツールのテレメトリーには、固定の診断コンテキストも含まれます。具体的には、例外クラスのエラーコード、スキーマで検証された引数名（値は含みません）、結果サイズのバケット、測定されたローカル DB 処理時間とリクエスト残り時間、UTC 時間、アプリのバージョン、任意の検証済み CNPJ_DEPLOY_VERSION ビルド ID です。CNPJ はローカルの DuckDB/Parquet を読み取るため、ライブの上流リクエストはなく（upstream_ms=0）、アプリケーションの結果キャッシュもありません（cache=not_applicable）。upstream=DB は DB 処理が使用されたことを意味しますが、DB が障害の原因である証拠ではありません。バッチ呼び出しではリクエストのタイミング／結果を共有します。不明または不完全な結果は unknown のままです。これらは既存のスパン／エラー／ログのプロパティであり、追加の分析イベントではありません。

集計プロダクト分析は、CNPJ_POSTHOG_ANALYTICS=1 によって別途オプトインできます。完了した HTTP ツール呼び出しごとに tool_called イベントを 1 件追加します。イベントには、ツール、ステータス、所要時間のバケット、測定された結果のバケット、スキーマで検証された引数名、既知のクライアント名／バージョンが含まれます。イベントごとに SDK が新たに生成した匿名 ID を保持し、ユーザープロフィールと GeoIP は無効にします。値、クエリテキスト、生の結果、エラー、セッション、クライアント IP／User-Agent、継承された ID はエクスポートされません。これにより、ツール／クライアントの構成比、空の結果の割合、フィルター名の採用状況、レイテンシの推移を集計できますが、ユーザー維持率、セッション、シーケンス、ファネルは分析できません。イベント数が増加するため、有効にする前にプロダクト分析の課金上限を確認してください。このフラグがない場合、既存の診断テレメトリーの動作は変わりません。

アプリケーションメトリクス（デフォルトでは無効）

CNPJ_POSTHOG_METRICS=1 を設定すると、PostHog アプリケーションメトリクス（オープンアルファ版）が有効になります。 プロジェクトの料金、クォータ、確実な請求上限を確認するまでは、本番環境で有効にしないでください。公開ドキュメントでは、メトリクスの無料枠、料金、上限は確定していません。アルファ版のデータ保持期間は30日です。このフラグはデフォルトでオフです。

Logs フラグおよび Analytics フラグとは独立した、手動で固定名を付けたメトリクスです。

• cnpj.tool.calls：カウンター。既知のツールと固定された結果のみを記録します。
• cnpj.tool.duration：正確な所要時間ではなく、上限バケット値のヒストグラムです。値は100、500、1000、5000、10000、または10001ミリ秒（オーバーフローを示す値）です。 SDK のヒストグラムで使用する境界値は固定のデフォルト値であり、カスタム境界値ではありません。 分位数はバケットによる近似値です。オーバーフローは10秒超を意味し、正確に10001ミリ秒を意味するものではありません。
• cnpj.worker.busy：アイドル時も含め、60秒ごとにサンプリングする0/1のゲージです。 スナップショットでは短時間の作業を捉えられないことがあります。平均稼働率でも、稼働率のSLOでもありません。
• cnpj.worker.rejected：実際の単一ワーカーの拒否分岐から取得するカウンターです。 架空のキュー深度メトリクスはありません。このサービスはスキャンをキューに入れず、拒否します。

このプロトタイプにはメモリメトリクスはありません。オプションのメモリ監視は先送りされました。 最大66個の系列：8つのツール × 7つの結果、8つのツールヒストグラム、busy、rejections。 未知のツールやステータスは、新しい系列を作成せずに破棄されます。SDK のガードは、ウィンドウごとに66系列、60秒ごとのフラッシュ、メモリ内集計、上限付きリトライです。 実際のワイヤーテストにより、ID、クライアントラベル、MCP の引数や結果、IP／UA、ホスト／PID、エグザンプラー、トレース ID が送信されないことを確認しています。リソース属性は固定のサービス名とSDK名／バージョンです。既存のエクスポーターと同様に、サーバーのトランスポートIP／エクスポーターUAは受信サービスに表示されます。

正常なシャットダウン時にはサンプラーが停止し、最後の集計がフラッシュされます。異常終了すると、ウィンドウ内のデータが失われる可能性があります。SDK のリトライは少なくとも1回の配信を保証する方式であり、ネットワーク障害の結果が不明確な場合、差分が重複することがあります。ウィザード、自動計装、スクレイピングエージェントはありません。

最小限の標準MCP Analyticsアダプター

CNPJ_POSTHOG_MCP_ANALYTICS=1 を設定すると、認識されたHTTPツール呼び出しが完了するたびに、標準の $mcp_tool_call イベントを1つ送信します。これは CNPJ_POSTHOG_ANALYTICS より優先されます。標準イベントに置き換わるため、tool_called と両方が送信されることはありません。 このフラグが設定されていない場合、既存の集計分析の動作は変わりません。

これは手動の許可リスト方式のアダプターであり、デフォルトの posthog.mcp.instrument やウィザードによるインストールではありません。ツールスキーマ、レスポンス、セッショントークンは変更されません。 標準フィールド：固定のソース／インターフェース／サーバー名／バージョン、登録済みのツール名／リソース名、エラーを示すブール値と固定のエラー分類、バケットを代表する数値の所要時間。10001ミリ秒は10秒超を意味し、正確な測定値ではありません。クライアントフィールド、引数や名前、結果／バケット、インテント、モデル、ユーザーエージェント／ベンダーヘッダー、IP、セッション／会話／人物情報、生のエラーテキストは含まれません。イベントごとに新しいランダムなSDK匿名IDを使用し、プロファイルとGeoIPはオフです。既存のサニタイズ済み診断／メトリクスは引き続き独立して動作し、MCP固有の例外イベントは追加されません。

アクティビティフィード／SQLでは、標準イベント名とフィールドを使用できます。ネイティブのMCPツール別呼び出し／エラー／レイテンシビューを目標としていますが、セッションIDがないため検証されていません。すべてのネイティブUIクエリがこの簡略化された形式を受け付ける保証はありません。レイテンシのパーセンタイルはバケットによる近似値です。このモードでは、セッションのタイムライン、シーケンス、ユーザーリテンション、モデル比較、インテントクラスター、機能不足レポート、広告されたものの未使用のツールとの結合に必要なデータはありません。過去の tool_called イベントは以前のイベント名のまま残り、バックフィルや削除は行われません。

これらは標準イベントであり、新たな100万件の無料枠ではなく、他のイベントとともにProduct Analyticsの利用枠／上限を共有します。実際の上限は未確認です。AIのインテント／要約機能が無料だと想定したり、このアダプターと併せて有効にしたりしないでください。

エラーのトリアージ（オプトイン）

CNPJ_POSTHOG_ERROR_TRIAGE=1 を設定すると、固定された合成の問題タイトル／フィンガープリント、正確な処理済み／合成の仕組み、および限定的な想定エラーフィルタリングが有効になります。 このフラグが設定されていない場合、従来の例外選択と形式は変更されません。 生の例外オブジェクト、メッセージ、トレース、ローカル変数、ID、セッションは追加されません。

グループ化は cnpj:v1:<registered-tool>:<fixed-error-class> であり、デプロイやクライアントごとではありません。問題のタイトルは、ツール名と固定されたクラスの種類です。既存の古い問題の名前変更や遡及的な補完は行われません。粗いグループには、複数の根本原因が含まれる場合があります。捕捉されたツール／RPC／HTTP の失敗には処理済みのマークが付きます。外部へ伝播する ASGI 例外や中断されたリクエストに、誤って処理済みのマークが付くことはありません。すべてのレポートは合成であり、スタックトレースを捏造することはありません。

明示的にマークされた次の3つの想定結果のみ、$exception の報告対象外になります。

• 独自のツールコードにある検証ガード（ExpectedValidationError。メッセージは同一のまま、引き続き ValueError です）。通常の ValueError／TypeError、信頼できるマーカーがない SDK スキーマエラー、利用できない contact-score テーブルは引き続き報告対象です。
• 実際の単一ワーカーのビジーゲート（WorkerBusyError。メッセージは同一のまま、引き続き RuntimeError です）。メッセージを読み取らずに rate_limit に分類されます。
• 明示的な get_company のスナップショットに存在しない場合の分岐。これはすでに通常の結果エンベロープを返しており、通常は例外も出力していません。そのため、新たな件数削減とはみなされません。結果やエラーに対する文字列照合は行いません。

その他の一般的な tool_error／rpc_error、信頼できる分岐マーカーがない HTTP4xx／429、タイムアウト、データベース／内部エラー、中断は引き続き報告対象です。現在、レートリミッターはツールのテレメトリーの外部で動作するため、単独の HTTP429 イベントが追加または抑制されることはありません。想定結果も含め、既存の Logs、Traces、Metrics、正規の呼び出しイベントはすべて引き続き記録されます。フィルタリングによって、運用カウンターから除外されることはありません。リリースへのリンク付けとアラートは、このビルドには含まれません。