| Name | cnpj-mcp-server JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | A MCP server for CNPJ search using buscadordecnpj.com API |
| upload_time | 2025-08-02 09:35:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
api
brazil
cnpj
company
mcp
search
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CNPJ MCP Server
Um servidor MCP (Model Context Protocol) para busca de dados de empresas brasileiras usando a API do [buscadordecnpj.com](https://buscadordecnpj.com).
## 📋 Funcionalidades
### 🆓 Consultas Gratuitas
- **cnpj_public_lookup**: Busca pública de dados básicos de uma empresa (sem necessidade de API key)
### 💎 Consultas Premium (requer API key)
- **cnpj_detailed_lookup**: Busca detalhada com dados completos da empresa
- **cnpj_bulk_lookup**: Busca em lote de múltiplos CNPJs (até 20 por requisição)
- **cnpj_advanced_search**: Busca avançada com filtros personalizados
## 🚀 Instalação
### Pré-requisitos
- Python 3.11 ou superior
- pip
### 1. Clone e instale o projeto
```bash
git clone <repo-url>
cd cnpj-mcp-server
pip install -e .
```
### 2. Configure a API key (opcional para funcionalidades premium)
```bash
# Copie o arquivo de exemplo
cp .env.example .env
# Edite o arquivo .env e adicione sua API key
echo "CNPJ_API_KEY=sua_api_key_aqui" > .env
```
Para obter uma API key, visite: https://buscadordecnpj.com
## 🔧 Configuração no Claude Desktop
### 1. Edite o arquivo de configuração do Claude
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
### 2. Adicione a configuração do MCP server
```json
{
"mcpServers": {
"cnpj-search": {
"command": "cnpj-mcp-server",
"env": {
"CNPJ_API_KEY": "sua_api_key_aqui"
}
}
}
}
```
### 3. Reinicie o Claude Desktop
Feche e abra novamente o Claude Desktop para carregar o novo servidor MCP.
## 📖 Como Usar
### Consulta Pública (Gratuita)
```
Busque informações da empresa com CNPJ 11.222.333/0001-81
```
### Busca Detalhada (Premium)
```
Faça uma busca detalhada da empresa com CNPJ 11.222.333/0001-81
```
### Busca em Lote
```
Busque informações das empresas com CNPJs: 11.222.333/0001-81, 22.333.444/0001-92
```
### Busca Avançada
```
Busque empresas com nome "Petrobras" no estado do Rio de Janeiro que estejam ativas
```
## 🛠️ Exemplos de Uso Direto
### 1. Consulta Pública
```json
{
"tool": "cnpj_public_lookup",
"arguments": {
"cnpj": "11.222.333/0001-81"
}
}
```
### 2. Busca Detalhada
```json
{
"tool": "cnpj_detailed_lookup",
"arguments": {
"cnpj": "11222333000181"
}
}
```
### 3. Busca em Lote
```json
{
"tool": "cnpj_bulk_lookup",
"arguments": {
"cnpjs": ["11222333000181", "22333444000192"],
"state": "SP",
"active": true
}
}
```
### 4. Busca Avançada
```json
{
"tool": "cnpj_advanced_search",
"arguments": {
"name": "Petrobras",
"state": "RJ",
"registration_status": "ATIVA",
"page": 1,
"per_page": 10
}
}
```
## 🔍 Parâmetros Disponíveis
### cnpj_public_lookup
- **cnpj** (obrigatório): CNPJ da empresa (com ou sem formatação)
### cnpj_detailed_lookup
- **cnpj** (obrigatório): CNPJ da empresa (com ou sem formatação)
### cnpj_bulk_lookup
- **cnpjs** (obrigatório): Lista de CNPJs
- **state** (opcional): Filtrar por estado (UF)
- **active** (opcional): Filtrar apenas empresas ativas (true/false)
### cnpj_advanced_search
- **name** (opcional): Nome da empresa ou parte do nome
- **activity** (opcional): Atividade principal da empresa
- **state** (opcional): Estado (UF)
- **city** (opcional): Cidade
- **registration_status** (opcional): Status do registro (ATIVA, BAIXADA, etc.)
- **page** (opcional): Página dos resultados (padrão: 1)
- **per_page** (opcional): Resultados por página (máximo: 50)
## 💰 Custos da API
- **Consulta Pública**: Gratuita e ilimitada
- **Consulta Detalhada**: 1 crédito por consulta bem-sucedida
- **Busca em Lote**: 1 crédito por 20 CNPJs
- **Busca Avançada**: 2 créditos por busca
## 🚨 Solução de Problemas
### Erro: "API key required"
Certifique-se de que:
1. O arquivo `.env` existe na raiz do projeto
2. A variável `CNPJ_API_KEY` está definida corretamente
3. A API key é válida e tem créditos disponíveis
### Erro: "Unknown tool"
Verifique se:
1. O servidor MCP está rodando corretamente
2. O Claude Desktop foi reiniciado após a configuração
3. O nome da ferramenta está correto
### Servidor não inicia
Confirme que:
1. Python 3.11+ está instalado
2. As dependências foram instaladas com `pip install -e .`
3. Não há conflitos de porta
## 📞 Suporte
- **API**: https://buscadordecnpj.com
- **Documentação da API**: https://api.buscadordecnpj.com/docs
- **MCP Protocol**: https://modelcontextprotocol.io
## 📄 Licença
Este projeto está licenciado sob a MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "cnpj-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "api, brazil, cnpj, company, mcp, search",
"author": null,
"author_email": "Buscador de CNPJ <contato@buscadordecnpj.com>",
"download_url": "https://files.pythonhosted.org/packages/fd/7d/23378df8effad4bbc2ef16f9762fcb4873edb3d5542d09538a14cc43efcc/cnpj_mcp_server-0.1.1.tar.gz",
"platform": null,
"description": "# CNPJ MCP Server\n\nUm servidor MCP (Model Context Protocol) para busca de dados de empresas brasileiras usando a API do [buscadordecnpj.com](https://buscadordecnpj.com).\n\n## \ud83d\udccb Funcionalidades\n\n### \ud83c\udd93 Consultas Gratuitas\n- **cnpj_public_lookup**: Busca p\u00fablica de dados b\u00e1sicos de uma empresa (sem necessidade de API key)\n\n### \ud83d\udc8e Consultas Premium (requer API key)\n- **cnpj_detailed_lookup**: Busca detalhada com dados completos da empresa\n- **cnpj_bulk_lookup**: Busca em lote de m\u00faltiplos CNPJs (at\u00e9 20 por requisi\u00e7\u00e3o)\n- **cnpj_advanced_search**: Busca avan\u00e7ada com filtros personalizados\n\n## \ud83d\ude80 Instala\u00e7\u00e3o\n\n### Pr\u00e9-requisitos\n- Python 3.11 ou superior\n- pip\n\n### 1. Clone e instale o projeto\n```bash\ngit clone <repo-url>\ncd cnpj-mcp-server\npip install -e .\n```\n\n### 2. Configure a API key (opcional para funcionalidades premium)\n```bash\n# Copie o arquivo de exemplo\ncp .env.example .env\n\n# Edite o arquivo .env e adicione sua API key\necho \"CNPJ_API_KEY=sua_api_key_aqui\" > .env\n```\n\nPara obter uma API key, visite: https://buscadordecnpj.com\n\n## \ud83d\udd27 Configura\u00e7\u00e3o no Claude Desktop\n\n### 1. Edite o arquivo de configura\u00e7\u00e3o do Claude\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### 2. Adicione a configura\u00e7\u00e3o do MCP server\n```json\n{\n \"mcpServers\": {\n \"cnpj-search\": {\n \"command\": \"cnpj-mcp-server\",\n \"env\": {\n \"CNPJ_API_KEY\": \"sua_api_key_aqui\"\n }\n }\n }\n}\n```\n\n### 3. Reinicie o Claude Desktop\nFeche e abra novamente o Claude Desktop para carregar o novo servidor MCP.\n\n## \ud83d\udcd6 Como Usar\n\n### Consulta P\u00fablica (Gratuita)\n```\nBusque informa\u00e7\u00f5es da empresa com CNPJ 11.222.333/0001-81\n```\n\n### Busca Detalhada (Premium)\n```\nFa\u00e7a uma busca detalhada da empresa com CNPJ 11.222.333/0001-81\n```\n\n### Busca em Lote\n```\nBusque informa\u00e7\u00f5es das empresas com CNPJs: 11.222.333/0001-81, 22.333.444/0001-92\n```\n\n### Busca Avan\u00e7ada\n```\nBusque empresas com nome \"Petrobras\" no estado do Rio de Janeiro que estejam ativas\n```\n\n## \ud83d\udee0\ufe0f Exemplos de Uso Direto\n\n### 1. Consulta P\u00fablica\n```json\n{\n \"tool\": \"cnpj_public_lookup\",\n \"arguments\": {\n \"cnpj\": \"11.222.333/0001-81\"\n }\n}\n```\n\n### 2. Busca Detalhada\n```json\n{\n \"tool\": \"cnpj_detailed_lookup\",\n \"arguments\": {\n \"cnpj\": \"11222333000181\"\n }\n}\n```\n\n### 3. Busca em Lote\n```json\n{\n \"tool\": \"cnpj_bulk_lookup\",\n \"arguments\": {\n \"cnpjs\": [\"11222333000181\", \"22333444000192\"],\n \"state\": \"SP\",\n \"active\": true\n }\n}\n```\n\n### 4. Busca Avan\u00e7ada\n```json\n{\n \"tool\": \"cnpj_advanced_search\",\n \"arguments\": {\n \"name\": \"Petrobras\",\n \"state\": \"RJ\",\n \"registration_status\": \"ATIVA\",\n \"page\": 1,\n \"per_page\": 10\n }\n}\n```\n\n## \ud83d\udd0d Par\u00e2metros Dispon\u00edveis\n\n### cnpj_public_lookup\n- **cnpj** (obrigat\u00f3rio): CNPJ da empresa (com ou sem formata\u00e7\u00e3o)\n\n### cnpj_detailed_lookup\n- **cnpj** (obrigat\u00f3rio): CNPJ da empresa (com ou sem formata\u00e7\u00e3o)\n\n### cnpj_bulk_lookup\n- **cnpjs** (obrigat\u00f3rio): Lista de CNPJs\n- **state** (opcional): Filtrar por estado (UF)\n- **active** (opcional): Filtrar apenas empresas ativas (true/false)\n\n### cnpj_advanced_search\n- **name** (opcional): Nome da empresa ou parte do nome\n- **activity** (opcional): Atividade principal da empresa\n- **state** (opcional): Estado (UF)\n- **city** (opcional): Cidade\n- **registration_status** (opcional): Status do registro (ATIVA, BAIXADA, etc.)\n- **page** (opcional): P\u00e1gina dos resultados (padr\u00e3o: 1)\n- **per_page** (opcional): Resultados por p\u00e1gina (m\u00e1ximo: 50)\n\n## \ud83d\udcb0 Custos da API\n\n- **Consulta P\u00fablica**: Gratuita e ilimitada\n- **Consulta Detalhada**: 1 cr\u00e9dito por consulta bem-sucedida\n- **Busca em Lote**: 1 cr\u00e9dito por 20 CNPJs\n- **Busca Avan\u00e7ada**: 2 cr\u00e9ditos por busca\n\n## \ud83d\udea8 Solu\u00e7\u00e3o de Problemas\n\n### Erro: \"API key required\"\nCertifique-se de que:\n1. O arquivo `.env` existe na raiz do projeto\n2. A vari\u00e1vel `CNPJ_API_KEY` est\u00e1 definida corretamente\n3. A API key \u00e9 v\u00e1lida e tem cr\u00e9ditos dispon\u00edveis\n\n### Erro: \"Unknown tool\"\nVerifique se:\n1. O servidor MCP est\u00e1 rodando corretamente\n2. O Claude Desktop foi reiniciado ap\u00f3s a configura\u00e7\u00e3o\n3. O nome da ferramenta est\u00e1 correto\n\n### Servidor n\u00e3o inicia\nConfirme que:\n1. Python 3.11+ est\u00e1 instalado\n2. As depend\u00eancias foram instaladas com `pip install -e .`\n3. N\u00e3o h\u00e1 conflitos de porta\n\n## \ud83d\udcde Suporte\n\n- **API**: https://buscadordecnpj.com\n- **Documenta\u00e7\u00e3o da API**: https://api.buscadordecnpj.com/docs\n- **MCP Protocol**: https://modelcontextprotocol.io\n\n## \ud83d\udcc4 Licen\u00e7a\n\nEste projeto est\u00e1 licenciado sob a MIT License.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MCP server for CNPJ search using buscadordecnpj.com API",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/victortavernari/cnpj-mcp-server#readme",
"Homepage": "https://github.com/victortavernari/cnpj-mcp-server",
"Issues": "https://github.com/victortavernari/cnpj-mcp-server/issues",
"Repository": "https://github.com/victortavernari/cnpj-mcp-server"
},
"split_keywords": [
"api",
" brazil",
" cnpj",
" company",
" mcp",
" search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8fd83fa5f1d6fef11c66eded8a8ca4d5054e8061ff3de175a621b137e8001cef",
"md5": "7b353d37d46932237983188adaf5c591",
"sha256": "3a80c2106f26806300b4121612e88b9e0fe6d7e178eca40dace21562986f3048"
},
"downloads": -1,
"filename": "cnpj_mcp_server-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b353d37d46932237983188adaf5c591",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 6860,
"upload_time": "2025-08-02T09:35:15",
"upload_time_iso_8601": "2025-08-02T09:35:15.391103Z",
"url": "https://files.pythonhosted.org/packages/8f/d8/3fa5f1d6fef11c66eded8a8ca4d5054e8061ff3de175a621b137e8001cef/cnpj_mcp_server-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fd7d23378df8effad4bbc2ef16f9762fcb4873edb3d5542d09538a14cc43efcc",
"md5": "aad525c41615ee4a5ca199b745c66e36",
"sha256": "964fff30943cf81eb3c8a763c785f6439c36ed7b5ac710f61c248d25caa3736a"
},
"downloads": -1,
"filename": "cnpj_mcp_server-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "aad525c41615ee4a5ca199b745c66e36",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 6091,
"upload_time": "2025-08-02T09:35:16",
"upload_time_iso_8601": "2025-08-02T09:35:16.511394Z",
"url": "https://files.pythonhosted.org/packages/fd/7d/23378df8effad4bbc2ef16f9762fcb4873edb3d5542d09538a14cc43efcc/cnpj_mcp_server-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 09:35:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "victortavernari",
"github_project": "cnpj-mcp-server#readme",
"github_not_found": true,
"lcname": "cnpj-mcp-server"
}
