Claro Gerencial

ws-claro-gerencial-mcp

Claro Gerencial（Redeinova Tecnologia が管理する Claro のプラットフォーム）の WebServices SOAP と連携する MCP（Model Context Protocol）サーバーです。

このサーバーを使うと、AI エージェント（opencode、Claude Code など）が Claro Gerencial と直接やり取りし、データの照会や送信を自律的に実行できます。

機能

このサーバーは MCP 経由で 6 つのツールを公開します。

• listar_entidades — 利用可能なすべてのエンティティとその方向（input/output）を一覧表示します
• obter_registros — 任意のエンティティのレコードを照会します（全件または増分）
• gerar_arquivo — 照会チケットをもとに FTP ファイルの生成をリクエストします
• enviar_registros — レコードをインポートするための XML を送信します
• obter_status — 送信処理のステータスを照会します
• obter_schema_xml — 送信前の検証に使用する XSD スキーマを取得します

利用可能なエンティティ

• 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

インストール

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：すべての通信で TLS を使用した HTTPS が使われます。
• 認証：ユーザー名とパスワードは Redeinova から提供されます。パスワードは 8 文字以上の強固なものを使用してください。

IP による認可（output/baixa）

照会／データ取得（output）と送信（input）では、WebService は、マシンの 送信元 IP が RepositorioControleIntClaro.dbo.DistribuidorIP テーブル（Ip 列）で認可され、販売代理店のユーザー（例：CLAROREDEFLEXWS）に関連付けられ、Ativo = 1 になっていることを要求します。これを満たさない場合、WS は Usuário não autorizado para efetuar baixa と応答します。

確認時のヒント：

• VPN（例：redeinova-dc）を使用している場合、送信元 IP はトンネルインターフェース（utun*）のものです。次のコマンドで確認できます：ifconfig | grep "inet "
• WS のドメイン（clarogerencial.redeinova.com.br）は内部 IP（10.177.51.41）に解決されるため、通信は VPN 経由で送信されます。登録する IP は VPN インターフェースのものです。curl ifconfig.me が返すパブリック IP ではありません。
• 許可または変更するには：RepositorioControleIntClaro.dbo.DistribuidorIP に対して INSERT／UPDATE を実行します。

検証環境

検証環境をリクエストするには、以下までお問い合わせください。

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

ライセンス

MIT