Claro Gerencial

ws-claro-gerencial-mcp

用于与 Claro Gerencial（由 Redeinova Tecnologia 管理的 Claro 平台）的 SOAP Web 服务集成的 MCP（Model Context Protocol）服务。

此服务允许 AI Agent（如 opencode、Claude Code 等）直接与 Claro Gerencial 交互，自主执行数据查询和发送。

功能

该服务通过 MCP 提供 6 个工具：

• listar_entidades — 列出所有可用实体及其方向（输入/输出）
• obter_registros — 查询任意实体的记录（完整或增量）
• gerar_arquivo — 根据查询票据请求生成 FTP 文件
• enviar_registros — 发送用于导入记录的 XML
• obter_status — 查询数据发送的处理状态
• obter_schema_xml — 获取用于发送前验证的 XSD schema

可用实体

• 城市、街区、客户（PDV）、客户访问、公司、经理、主管
• 销售人员、部门、产品组、访问原因、产品、细分市场
• 客户类型、标记类型、客户标记、访问
• 集成商、订单、销售人员芯片、MotivosICCIDS、ICCID、PDV 网络
• 宽带销售、ICCID 重读

安装

pip install ws-claro-gerencial-mcp

或者，无需安装任何内容（直接从 PyPI 运行，并使用缓存）：

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

或者用于开发：

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

配置

在项目根目录创建 .env 文件，或设置环境变量：

CLARO_USUARIO=seu_usuario
CLARO_SENHA=sua_senha
CLARO_AMBIENTE=homologacao

环境变量

变量	必填	默认值	描述
CLARO_USUARIO	是	—	访问 Web 服务的用户名
CLARO_SENHA	是	—	访问 Web 服务的密码
CLARO_AMBIENTE	否	homologacao	环境：homologacao 或 producao
CLARO_URL_BASE_OUTPUT	否	https://clarogerencial.redeinova.com.br/wsoutput	Output WS 的基础 URL
CLARO_URL_BASE_INPUT	否	https://clarogerencial.redeinova.com.br/wsinput	Input WS 的基础 URL

与 MCP 客户端配合使用

Claude Desktop

添加到 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

添加到项目的 opencode.json：

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

使用示例

> 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>

安全要求

• 固定 IP：分销商需要在 Redeinova 登记一个固定 IP。
• SSL：所有通信均使用 HTTPS 和 TLS。
• 身份验证：使用 Redeinova 提供的用户名和密码；密码至少为 8 个字符且应足够强。

IP 授权（output/baixa）

对于查询/下载（output）以及发送（input），Web 服务要求机器的源 IP已在 RepositorioControleIntClaro.dbo.DistribuidorIP 表（Ip 列）中获授权，并关联到分销商用户（例如 CLAROREDEFLEXWS），且 Ativo = 1。否则，WS 会返回 Usuário não autorizado para efetuar baixa。

验证提示：

• 使用 VPN（例如 redeinova-dc）时，源 IP 是隧道接口（utun*）的 IP。可通过以下命令查找：ifconfig | grep "inet ".
• WS 域名（clarogerencial.redeinova.com.br）会解析为内部 IP（10.177.51.41），因此流量会通过 VPN 发送。需要登记的是 VPN 接口的 IP，而不是 curl ifconfig.me 返回的公网 IP。
• 如需授权或调整：在 RepositorioControleIntClaro.dbo.DistribuidorIP 中执行 INSERT/UPDATE。

测试环境

如需申请测试环境，请联系：

• Redeinova Tecnologia：[email protected]
• 电话：+55 (85) 3032-5648 / 3252-3405

许可证

MIT