ws-claro-gerencial-mcp

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.git
cd ws-claro-gerencial-mcp
pip install -e .
Configuração
Crie um arquivo .env na raiz do projeto ou defina as variáveis de ambiente:
CLARO_USUARIO=seu_usuario
CLARO_SENHA=sua_senha
CLARO_AMBIENTE=homologacao
Variáveis de ambiente
| Variável | Obrigatória | Padrão | Descrição |
|---|
CLARO_USUARIO | Sim | — | Usuário de acesso ao webservice |
CLARO_SENHA | Sim | — | Senha de acesso ao webservice |
CLARO_AMBIENTE | Não | homologacao | Ambiente: homologacao ou producao |
CLARO_URL_BASE_OUTPUT | Não | https://clarogerencial.redeinova.com.br/wsoutput | URL base do WS de Output |
CLARO_URL_BASE_INPUT | Não | https://clarogerencial.redeinova.com.br/wsinput | URL base do WS de Input |
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:
Licença
MIT