Buscador De Cnpj

CNPJ 搜索器 - MCP 服务

一个使用 buscadordecnpj.com API 搜索巴西企业数据的 MCP（Model Context Protocol）服务。

📋 功能

🆓 免费查询

• cnpj_public_lookup：公开查询企业基本数据（无需 API 密钥）

💎 高级查询（需要 API 密钥）

• cnpj_detailed_lookup：详细查询企业完整数据
• term_search：使用自然语言在多个字段中按文本词语搜索；例如：“圣保罗市 Tatuapé 区的面包店”
• cnpj_advanced_search：使用结构化筛选条件（精确值、范围）进行高级搜索；适合微调

🚀 安装

🎯 自动安装（推荐）

curl -sSL https://raw.githubusercontent.com/victortavernari/buscador-de-cnpj/main/install.sh | bash

此脚本将：

• ✅ 检测您的操作系统
• ✅ 安装 uv（如有需要）
• ✅ 安装 buscador-de-cnpj
• ✅ 自动配置 Claude Desktop
• ✅ 创建用于兼容性的包装脚本

🔧 手动安装

选项 A：使用 uv

# Instale uv (se não tiver)
curl -LsSf https://astral.sh/uv/install.sh | sh
# ou no Windows:
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

选项 B：使用 pip

pip install buscador-de-cnpj

🔑 配置您的 API 密钥

如需使用高级功能，请在此处获取 API 密钥：https://buscadordecnpj.com

🔧 在 Claude Desktop 中配置

1. 编辑 Claude 配置文件

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 添加 MCP 服务配置

选项 A：使用带包装脚本的 uvx（推荐）

1. 创建包装脚本：

# Crie o diretório se não existir
sudo mkdir -p /usr/local/bin

# Crie o script wrapper
sudo tee /usr/local/bin/uvx-wrapper << 'EOF'
#!/bin/bash
# Encontra uvx automaticamente e executa
UVX_PATH=""

# Possíveis localizações do uvx
POSSIBLE_PATHS=(
    "$HOME/.local/bin/uvx"
    "$HOME/Library/Python/3.*/bin/uvx"
    "/opt/homebrew/bin/uvx"
    "/usr/local/bin/uvx"
    "$(which uvx 2>/dev/null)"
)

for path in "${POSSIBLE_PATHS[@]}"; do
    if [[ -x "$path" ]]; then
        UVX_PATH="$path"
        break
    fi
    # Para paths com wildcard
    for expanded in $path; do
        if [[ -x "$expanded" ]]; then
            UVX_PATH="$expanded"
            break 2
        fi
    done
done

if [[ -z "$UVX_PATH" ]]; then
    echo "Error: uvx not found. Please install uv first." >&2
    exit 1
fi

exec "$UVX_PATH" "$@"
EOF

# Torne executável
sudo chmod +x /usr/local/bin/uvx-wrapper

2. 在 Claude Desktop 中配置：

{
  "mcpServers": {
    "cnpj-search": {
      "command": "/usr/local/bin/uvx-wrapper",
      "args": ["buscador-de-cnpj"],
      "env": {
        "CNPJ_API_KEY": "sua_api_key_aqui"
      }
    }
  }
}

选项 B：使用 pip 全局安装（更简单）

pip install buscador-de-cnpj

{
  "mcpServers": {
    "cnpj-search": {
      "command": "buscador-de-cnpj",
      "env": {
        "CNPJ_API_KEY": "sua_api_key_aqui"
      }
    }
  }
}

选项 C：手动指定路径（如果其他选项不起作用）

1. 查找 uvx 的路径：

which uvx

2. 使用完整路径：

{
  "mcpServers": {
    "cnpj-search": {
      "command": "/seu/caminho/para/uvx",
      "args": ["buscador-de-cnpj"],
      "env": {
        "CNPJ_API_KEY": "sua_api_key_aqui"
      }
    }
  }
}

3. 重启 Claude Desktop

关闭并重新打开 Claude Desktop，以加载新的 MCP 服务。

📖 使用方法

有关部署、验证和最佳实践的详情，也请参阅 QWEN.md。

公开查询（免费）

Busque informações da empresa com CNPJ 11.222.333/0001-81

详细搜索（高级）

Faça uma busca detalhada da empresa com CNPJ 11.222.333/0001-81

批量搜索

Busque informações das empresas com CNPJs: 11.222.333/0001-81, 22.333.444/0001-92

高级搜索

Busque empresas com nome "Petrobras" no estado do Rio de Janeiro que estejam ativas

🛠️ 直接使用示例

1. 公开查询

{
  "tool": "cnpj_public_lookup",
  "arguments": {
    "cnpj": "11.222.333/0001-81"
  }
}

2. 详细搜索

{
  "tool": "cnpj_detailed_lookup",
  "arguments": {
    "cnpj": "11222333000181"
  }
}

3. 批量搜索

{
  "tool": "cnpj_bulk_lookup",
  "arguments": {
    "cnpjs": ["11222333000181", "22333444000192"],
    "state": "SP",
    "active": true
  }
}

4. 按词语搜索（自由文本）

{
  "tool": "term_search",
  "arguments": {
    "term": "padarias em SP Tatuapé",
    "uf": "SP",
    "pagina": 1,
    "limite": 100
  }
}

提示：使用 term 输入自然语言；结合 uf、municipio、bairro 可加快搜索并缩小范围。

5. 高级搜索（结构化筛选条件）

{
  "tool": "cnpj_advanced_search",
  "arguments": {
    "razao_social": "*padaria*",
    "uf": "SP",
    "municipio": "São Paulo",
    "bairro": "Tatuapé",
    "situacao_cadastral": "2",
    "pagina": 1,
    "limite": 100
  }
}

🔍 可用参数

cnpj_public_lookup

• cnpj（必填）：企业的 CNPJ（可带或不带格式）

cnpj_detailed_lookup

• cnpj（必填）：企业的 CNPJ（可带或不带格式）

cnpj_bulk_lookup

• cnpjs（必填）：CNPJ 列表
• state（可选）：按州筛选（UF）
• active（可选）：仅筛选活跃企业（true/false）

cnpj_advanced_search

• name（可选）：企业名称或部分名称
• activity（可选）：企业的主要经营活动
• state（可选）：州（UF）
• city（可选）：城市
• registration_status（可选）：注册状态（ATIVA、BAIXADA 等）
• page（可选）：结果页码（默认值：1）
• per_page（可选）：每页结果数（最多：50）

💰 API 费用

• 公开查询：免费且不限次数
• 详细查询：每次成功查询消耗 1 个额度
• 批量搜索：每 20 个 CNPJ 消耗 1 个额度
• 高级搜索：每次搜索消耗 2 个额度

🚨 故障排除

错误：“spawn uvx ENOENT”

Claude Desktop 找不到 uvx。解决方法：

1. 查找 uvx 的路径：

which uvx

2. 在配置中使用完整路径：

{
  "command": "/caminho/completo/para/uvx",
  "args": ["buscador-de-cnpj"]
}

3. 如果尚未安装 uvx：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

4. 或使用选项 B，通过 pip install 安装

错误："spawn buscador-de-cnpj ENOENT"

尚未全局安装该软件包。请运行：

pip install buscador-de-cnpj

错误："API key required"

使用高级功能：

1. 设置环境变量：export CNPJ_API_KEY="sua_key"
2. 或在 Claude Desktop 的配置文件中进行配置
3. 在此处获取 API key：https://buscadordecnpj.com

错误："Unknown tool"

请检查：

1. 配置完成后是否重启了 Claude Desktop
2. JSON 配置是否正确（无语法错误）
3. 服务名称是否正确："cnpj-search"

服务无法连接

请确认：

1. 已安装 Python 3.11+
2. 软件包已正确安装
3. 不存在依赖项冲突

🔍 调试

若要在本地测试 MCP 服务，请使用 MCP Inspector：

使用 uvx

npx @modelcontextprotocol/inspector uvx buscador-de-cnpj

使用 pip install

npx @modelcontextprotocol/inspector buscador-de-cnpj

这将打开一个 Web 界面，供你直接测试 MCP 服务的工具。

📞 支持

• API：https://buscadordecnpj.com
• API 文档：https://api.buscadordecnpj.com/docs
• MCP Protocol：https://modelcontextprotocol.io

📄 许可证

本项目根据 MIT License 授权。