Brazil CNPJ company registry

cnpj-mcp

一个用于查询巴西开放企业注册数据的分析型 MCP 服务，基于巴西联邦税务局（Receita Federal）每月发布的开放数据构建。它旨在回答涉及多家企业的问题，而非查询单个编号：

• 自 2023 年以来，米纳斯吉拉斯州每月新增了多少 MEI？
• 马托格罗索州哪些市镇活跃的谷物和大豆企业最多？
• 哪些企业共用同一地址？它们的合伙人是谁？
• 每年有多少企业注销？注销原因是什么？

也支持查询单个 CNPJ，但免费 API 已经能很好地完成此类查询。

包含的内容

Receita 数据集中的每条机构、企业、合伙人以及 Simples/MEI 记录，均已关联并进行类型化处理，以便快速查询。数据值保留葡萄牙语，与 Receita 发布时完全一致。请查看 dataset_info，了解已加载快照的月份和行数。

Receita 文件	行数据对应的内容
Estabelecimentos + Empresas + Simples	每个 CNPJ（总公司和分支机构）对应一行，包含企业、规模、资本、法律形式、MEI/Simples 标记、CNAE、地址和联系方式
Socios	每条合伙人关联对应一行，包含姓名（CPF 已由 Receita 屏蔽）
Cnaes, Municipios, Naturezas, Motivos, Paises, Qualificacoes	代码表

来源：巴西联邦税务局、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）或无效地址。
• 使用相同电子邮件的企业数量，以及使用相同电子邮件域名的企业数量。一家企业是良好信号；数十家通常意味着这是会计师或共享邮箱。
• 电子邮件是否与企业名称匹配。
• 电话类型（手机或固定电话；Receita 经常记录缺少第九位数字的手机号码）以及共用该电话号码的企业数量。

contact_score 取电子邮件评分和电话评分中的较高者。search_companies 的 min_contact_score 可设为 0–100 的整数或等级名称（low = 0，medium = 50，high = 85），仅保留登记联系方式评分达到或超过该值的企业。此评分不反映网站情况。系统会在读取每一页后进行筛选，因此一次调用最多检查 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，每个域名每秒最多发送一个请求，读取范围最多为首页加一个联系页面。不会保存 Cookie。

服务从 website_contacts.parquet（每个域名一行）读取结果，并在 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 月：724,996 个企业域名由 1 至 3 家公司使用。420,058 个网站成功加载（57.9%）。清理后，414,185 个网站显示可用的联系方式，4,004 个实际是停放页面或“网站不可用”页面（例如 static.uni5.net/indisponivel.php），另有 1,869 个会跳转至社交媒体或登录页面；这些网站不会返回联系方式。在 414,185 个可用网站中，40% 显示 WhatsApp 链接，55% 显示电话，54% 显示邮箱，51% 显示社交媒体主页；70% 至少显示 WhatsApp、电话或邮箱之一。其余网站无法访问（28% 没有 DNS 记录或无法连接）、返回错误页面，或因 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、邮箱）中出现的信息都会被丢弃，因为这些信息属于网站构建工具、主机或平台。该网站仅为候选匹配：它通过登记邮箱的域名查找，因此区块包含 "match": "candidate"。更新时，请针对新的域名列表重新运行爬虫。

引用数字前请先阅读

• 登记信息仅显示当前状态，不保留公司的历史地址、经营活动和资本。
• 约一半记录已关闭（situacao baixada）。如果只统计正常经营的公司，请按 situacao 筛选。
• 除非传入 unit='empresas'（仅统计 matriz），否则统计的是营业机构（每个 CNPJ 计一个）。
• Capital social 是公司以 BRL 申报的金额，不代表实际资产。
• Receita 数据的准确性取决于公司和登记机构所报告的信息。开业日期、CNAE 代码和地址可能有误或已过时。
• MEI 和 Simples 标记显示当前选项，并附有开始或结束日期。

个人数据与 LGPD

Receita 会公布合作伙伴名称，本项目也包含这些名称。根据 LGPD，即使这些数据已公开，它们仍属于个人数据：

• Receita 在发布前会遮蔽 CPF（仅显示中间 6 位数字），本项目也会保留遮蔽状态。请勿尝试据此重新识别个人。
• 相同的姓名可能对应不同的人。请勿将姓名匹配视为两条记录属于同一人的证据。
• 请将合作伙伴搜索用于正当目的，例如尽职调查、新闻报道或研究。请勿将其用于个人画像、骚扰或未经请求的营销。
• 联系方式（电子邮件、电话）也由 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"

查询安全

默认情况下，托管查询使用一个有界工作线程，并将请求查询时限设为 10 秒（CNPJ_QUERY_TIMEOUT）。并发的高开销请求会收到重试提示，而不会进入无界队列；健康检查和数据集元数据仍会及时响应。被中断的查询会返回错误，而不是部分结果。

公司名称子串筛选需要指定 uf，且字符数须为 3-256。合作伙伴子串搜索也需要指定 uf，并保留现有的最短名称长度要求。不支持跨全国范围的名称子串扫描。超时后，请按州、活动或日期范围缩小查询范围。不会新增索引、旁路进程或隐藏的扫描上限。

可选的 PostHog 可观测性

设置 CNPJ_POSTHOG_TOKEN 并将其存储在服务器的密钥存储中后，HTTP 服务可以导出请求级工具跨度和已清理的错误事件。 未设置令牌时不会导出数据。 CNPJ_POSTHOG_HOST 默认为 https://us.i.posthog.com；欧盟项目可以使用 https://eu.i.posthog.com。请勿将项目令牌放入源代码或配置文件中。

只会导出工具名称、状态、耗时以及已知客户端的名称和版本。 错误事件会保留 SDK 生成的匿名 ID，但不会创建个人档案。不会导出参数、筛选值、查询文本、结果、调用方 IP/User-Agent、会话、原始异常消息、堆栈跟踪或局部变量。错误使用内置类型或 ToolError，并采用固定消息。不会导出握手和健康检查。批量调用共用其请求耗时和状态。客户端名称和版本是由客户端提供并经过清理的标签，并非经过验证的身份信息。在传输层，PostHog 仍会看到服务器的出口 IP 和 SDK User-Agent。

导出器使用有界异步队列。ASGI 正常关闭时会尝试进行最后一次刷新；意外终止或网络故障可能导致遥测数据丢失。现有的 SQLite 使用日志独立运行。导出失败不会影响工具响应。未启用广泛的自动插桩或异常自动捕获。

依赖零成本上限前，请先设置并验证产品的计费限制。摄取接口返回 HTTP 200 并不能证明事件会显示在项目界面中。完成设置后，请使用安全的合成请求检查追踪和错误跟踪是否正常。 运行 pytest tests/test_observability.py，执行离线 SDK 线路隐私和响应透明度检查。tests/compare_http_responses.py CHECKOUT [enabled] 在 CNPJ_DATA_DIR 指向同一测试数据集时，会对全部 8 个 HTTP 工具响应进行快照。可选的 enabled 参数使用虚拟凭据和拦截式网络传输；不会发送遥测数据。

可选的结构化日志导出由 CNPJ_POSTHOG_LOGS=1 单独控制。它使用相同的密钥和区域，通过 OTLP/protobuf 发送到 /i/v1/logs。仅发送固定的工具完成／失败消息、严重级别、时间戳和相同的允许列表工具元数据。不会安装根处理程序：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 事件，其中包含工具、状态、时长区间、测得的结果区间、经架构检查的参数名称，以及已知的客户端名称／版本。每个事件都会保留 SDK 新生成的匿名 ID，并禁用人员档案和 GeoIP。不导出任何值、查询文本、原始结果、错误、会话、客户端 IP/User-Agent 或继承的身份信息。这支持聚合工具／客户端分布、空结果率、筛选器名称使用情况和延迟趋势，但不支持用户留存、会话、序列或漏斗分析。它会增加事件量；启用前请确认产品分析计费上限。未设置此标志时，现有诊断遥测行为保持不变。

应用指标（默认关闭）

CNPJ_POSTHOG_METRICS=1 可选择启用 PostHog 应用指标（开放 Alpha）。 在确认项目价格、配额和硬性账单上限之前，请勿在生产环境中启用。 公开文档未明确说明 Metrics 的免费层级、价格或上限；Alpha 数据保留 30 天。该标志默认关闭。

手动定义的固定名称指标，独立于 Logs 和 Analytics 标志：

• cnpj.tool.calls：计数器，仅统计已知工具和固定结果。
• cnpj.tool.duration：直方图，记录的是上界桶值，而非精确时长： 100、500、1000、5000、10000 或 10001 ms（溢出哨兵值）。 SDK 直方图的线上边界采用其固定默认值，而非自定义边界。 分位数是桶的近似值；溢出表示 >10s，而非恰好 10001ms。
• cnpj.worker.busy：每 60 秒采样一次的 0/1 量表，包括空闲状态。 快照可能漏掉短时工作。它不是平均占用率或利用率 SLO。
• cnpj.worker.rejected：来自实际单工作线程拒绝分支的计数器。 不会虚构队列深度指标；此服务会拒绝扫描，而非将其排队。

此原型不包含内存指标。可选的内存监控已延期。 最多 66 个序列：8 个工具 x 7 种结果、8 个工具直方图、忙闲状态和拒绝数。 未知工具/状态会被丢弃，不会产生新序列。SDK 防护措施包括每个窗口 最多 66 个序列、每 60 秒刷新一次、内存聚合和有界重试。 实际线路测试确认不会发送身份信息、客户端标签、MCP 参数/结果、 IP/UA、主机/PID、示例或跟踪 ID。资源属性仅包含固定服务 名称以及 SDK 名称/版本。与现有导出器一样，接收服务仍可看到服务端传输 IP/导出器 UA。

正常关闭时，采样器会停止并刷新最后一次聚合；强制终止可能导致数据窗口丢失。 SDK 重试采用至少一次语义，在网络故障情况不明确时，可能重复发送增量数据。 没有向导、自动插桩或抓取 Agent。

最小化规范 MCP Analytics 适配器

CNPJ_POSTHOG_MCP_ANALYTICS=1 可选择为每次已识别且完成的 HTTP 工具调用 发送一个规范的 $mcp_tool_call 事件。它优先于 CNPJ_POSTHOG_ANALYTICS：规范事件会取代 tool_called，绝不会同时发送。 未设置该标志时，现有聚合分析行为保持不变。

这是一个手动的允许列表适配器，不是默认的 posthog.mcp.instrument 或向导安装方式。不更改工具架构、响应或会话令牌。 规范字段包括：固定的来源/接口/服务名称/版本、已注册的工具 名称/资源名称、错误布尔值和固定错误类别、桶代表性数值时长。 10001ms 表示 >10s，而非精确测量值。不包含客户端字段、 参数或名称、结果/桶、意图、模型、用户代理/厂商标头、 IP、会话/对话/用户资料或原始错误文本。每个事件使用新的随机 SDK 匿名 ID；关闭用户资料和 GeoIP。现有的脱敏诊断信息/Metrics 会独立 继续运行，不会额外产生 MCP 专属异常事件。

活动流/SQL 可使用规范事件名称和字段。目标是原生 MCP 单工具调用/错误/延迟视图，但在没有会话 ID 的情况下未经验证；无法保证所有原生 UI 查询都接受这种精简格式。延迟 百分位数是桶的近似值。此模式下不会有会话时间线、序列、用户 留存、模型对比、意图聚类、缺失能力报告以及已公布但未使用工具的关联查询。 历史 tool_called 事件仍保留原事件名称；不会回填或删除。

这些是标准事件，会与其他事件共享 Product Analytics 配额/限制，并非新增的 100 万免费额度。实际限额仍未验证。不要假定 AI 意图/摘要功能免费，也不要通过此适配器启用这些功能。

错误分流（可选启用）

CNPJ_POSTHOG_ERROR_TRIAGE=1 会启用固定的合成问题标题和指纹、如实标记已处理／合成机制，并对预期错误进行狭义过滤。 未设置该标志时，异常选择方式和格式与之前保持不变。 不会添加原始异常对象、消息、堆栈跟踪、局部变量、身份信息或会话信息。

分组格式为 cnpj:v1:<registered-tool>:<fixed-error-class>，而非按部署或客户端分组。问题标题由工具名称和固定的类类型组成。现有旧问题不会重命名或补录数据。粗略分组仍可能包含多个根因。 捕获到的工具／RPC／HTTP 失败会标记为已处理；向外传播的 ASGI 异常和中止的请求不会被错误地标记为已处理。所有报告均为合成报告，不会伪造堆栈跟踪。

只有以下三种明确标记的预期结果会抑制 $exception：

• 我们自己的工具代码中的验证保护（ExpectedValidationError，仍是 ValueError，且消息相同）。普通 ValueError/TypeError、没有可信标记的 SDK 模式验证失败，以及不可用的联系评分表仍会报告。
• 实际的单工作进程繁忙门控（WorkerBusyError，仍是 RuntimeError，且消息相同）。分类为 rate_limit，不读取其消息。
• 明确的 get_company 未包含在快照中的分支。该分支本来就会返回正常的结果信封，通常也不会产生异常；不会声称这能降低新产生的事件量。不会对结果／错误进行字符串匹配。

其他通用 tool_error/rpc_error、没有可信分支标记的 HTTP4xx/429、超时、数据库／内部故障和中止仍符合报告条件。目前，速率限制器在工具遥测范围之外运行，因此此更改不会增加或抑制其独立的 HTTP429 事件。所有现有的 Logs、Traces、Metrics 和规范调用事件仍会继续记录，包括预期结果。过滤不会将这些事件从运维计数器中隐藏。此版本不包含发布关联和告警。