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

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: suporte@redeinova.net
• Telefone: +55 (85) 3032-5648 / 3252-3405

Licença

MIT