Claro Gerencial

ws-claro-gerencial-mcp

[PyPI version] [License: MIT] [Python versions]

Servidor MCP (Model Context Protocol) para integração com os WebServices SOAP do Claro Gerencial (plataforma da Claro gerenciada pela Redeinova Tecnologia).

Este servidor permite que agentes de IA (como o opencode, Claude Code, etc.) interajam diretamente com o Claro Gerencial, realizando consultas e envios de dados de forma autônoma.

Funcionalidades

O servidor expõe 6 ferramentas via MCP:

• listar_entidades — Lista todas as entidades disponíveis e suas direções (input/output)
• obter_registros — Consulta registros de qualquer entidade (completa ou incremental)
• gerar_arquivo — Solicita geração de arquivo FTP a partir de um ticket de consulta
• enviar_registros — Envia XML para importação de registros
• obter_status — Consulta status de processamento de um envio
• obter_schema_xml — Obtém schema XSD para validação antes do envio

Entidades disponíveis

• Cidades, Bairros, Clientes (PDVs), ClientesVisitas, Empresas, Gerentes, Supervisores
• Vendedores, Setores, Grupos de Produtos, MotivosVisitas, Produtos, Segmentos
• TiposClientes, TiposSinalizações, ClientesSinalizações, Visitas
• Integradores, Pedidos, ChipsVendedor, MotivosICCIDS, ICCID, RedesPDV
• VendasBandaLarga, ReleiturasICCID

Instalação

pip install ws-claro-gerencial-mcp

Ou, sem instalar nada (executa direto do PyPI com cache):

uvx --from ws-claro-gerencial-mcp ws-claro-gerencial-mcp

Ou para desenvolvimento:

git clone https://github.com/hlgurgel/ws-claro-gerencial-mcp.gitcd ws-claro-gerencial-mcppip install -e .

Configuração

Crie um arquivo .env na raiz do projeto ou defina as variáveis de ambiente:

CLARO_USUARIO=seu_usuarioCLARO_SENHA=sua_senhaCLARO_AMBIENTE=homologacao

Variáveis de ambiente

Uso com clientes MCP

Claude Desktop

Adicione ao claude_desktop_config.json:

{  "mcpServers": {    "claro-gerencial": {      "command": "uvx",      "args": ["--from", "ws-claro-gerencial-mcp", "ws-claro-gerencial-mcp"],      "env": {        "CLARO_USUARIO": "seu_usuario",        "CLARO_SENHA": "sua_senha",        "CLARO_AMBIENTE": "homologacao"      }    }  }}

OpenCode

Adicione ao opencode.json do seu projeto:

{  "mcp": {    "claro-gerencial": {      "type": "local",      "command": ["ws-claro-gerencial-mcp"],      "environment": {        "CLARO_USUARIO": "seu_usuario",        "CLARO_SENHA": "sua_senha",        "CLARO_AMBIENTE": "homologacao"      }    }  }}

Exemplos de uso

> Liste as entidades disponíveis no Claro Gerencial.
> Consulte os clientes ativos (entidade: 'clientes') de forma completa.
> Envie um novo cliente:<Clientes>  <Cliente>    <Empresa>1</Empresa>    <Sequencial>999</Sequencial>    <Nome>NOVO PDV</Nome>    <DbAcao>I</DbAcao>  </Cliente></Clientes>

Requisitos de segurança

• IP fixo: O distribuidor precisa ter um IP fixo cadastrado na Redeinova.
• SSL: Toda comunicação usa HTTPS com TLS.
• Autenticação: Usuário e senha fornecidos pela Redeinova, senhas fortes com mínimo de 8 caracteres.

Autorização por IP (output/baixa)

Para consultas/baixas (output) — e também envios (input) — o WebService exige que o IP de origem da máquina esteja autorizado na tabela RepositorioControleIntClaro.dbo.DistribuidorIP (coluna Ip), associado ao usuário do distribuidor (ex.: CLAROREDEFLEXWS) com Ativo = 1. Sem isso, o WS responde Usuário não autorizado para efetuar baixa.

Dicas para validação:

• Em VPN (ex.: redeinova-dc), o IP de origem é o da interface de túnel (utun*). Descobrir com: ifconfig | grep "inet ".
• O domínio do WS (clarogerencial.redeinova.com.br) resolve para IP interno (10.177.51.41), então o tráfego sai pela VPN. O IP a cadastrar é o da interface VPN — não o IP público retornado por curl ifconfig.me.
• Para liberar/ajustar: INSERT/UPDATE em RepositorioControleIntClaro.dbo.DistribuidorIP.

Ambiente de homologação

Para solicitar ambiente de homologação, entre em contato com:

• Redeinova Tecnologia: [email protected]
• Telefone: +55 (85) 3032-5648 / 3252-3405

Licença

MIT