WIBI MCP 网关

服务器 MCP（模型上下文协议），将 WIBI API v2 作为工具暴露给 LLM 助手。

支持两种模式：

终端用户指南（WIBI 商户）

无需成为开发者，也无需编辑 JSON 文件。

Claude web（claude.ai）

1. 使用你的账户登录 claude.ai。

2. 前往 Settings → Connectors → Add custom connector。

3. 粘贴服务器 URL：https://wibi.com.ar/mcp （临时测试 URL；见 DNS 说明）。

4. Claude 会在浏览器中打开 WIBI 登录页面。

5. 输入 WIBI 用户名和密码：

   • 商户： 与系统中商户相同的凭据 → 直接访问。

   • 面板管理员： WIBI 面板用户名（非商户用户名）。若活动启用了 2FA，则需要输入邮件验证码。然后选择活动和商户，范围与面板一致（管理员看到自己的活动/商户；超级管理员看到全部）。

6. 授权。然后你就可以让 Claude 做这些事情，例如：

   • “列出我活动中的产品”

   • “查找 DNI 为 … 的客户”

   • “我有哪些活动？”

每个会话仅针对所选商户进行操作。没有共享令牌，也没有按客户端的配置。

Claude Desktop

1. 打开 Claude Desktop → Settings → Connectors（或 Developers，视版本而定）。

2. 添加一个远程连接器，URL 为 https://wibi.com.ar/mcp （临时；见 DNS 说明）。

3. 在浏览器中完成登录，输入你的 WIBI 用户名/密码。

Related MCP server: meta-ads-mcp

技术团队指南

要求

• Node.js >= 18

• WIBI 应用 API 密钥（approl 1 或 3）

• 已部署的 API v2（包含 /onzecrm/v2/auth/* 和 /onzecrm/v2/campanias）

安装

cd wibi-mcp-gateway
npm install --ignore-scripts
npm run build

stdio 模式（本地开发）

export WIBI_BASE_URL=https://apiv2.wibi.com.ar
export WIBI_API_KEY=...
export WIBI_USER=...
export WIBI_PASS=...
# opcional:
# export WIBI_DEFAULT_CAMPANIA=13793
node dist/index.js

mcp.json 示例（仅限本地开发）：

{
  "mcpServers": {
    "wibi-local": {
      "command": "node",
      "args": ["/ruta/a/wibi-mcp-gateway/dist/index.js"],
      "env": {
        "WIBI_BASE_URL": "https://apiv2.wibi.com.ar",
        "WIBI_API_KEY": "...",
        "WIBI_USER": "...",
        "WIBI_PASS": "..."
      }
    }
  }
}

HTTP + OAuth 模式（生产环境）

最低环境变量：

在此模式下不要配置 WIBI_USER、WIBI_PASS 或 MCP_HTTP_TOKEN：登录是交互式的（商户或面板管理员）。

MCP_TRANSPORT=http \
WIBI_BASE_URL=https://apiv2.wibi.com.ar \
WIBI_API_KEY=... \
WIBI_PUBLIC_URL=https://wibi.com.ar \
node dist/index.js --http

端点：

• GET /healthz — 健康检查

• GET /.well-known/oauth-authorization-server — OAuth 元数据

• POST /register — 动态客户端注册

• GET /authorize — 登录页面

• POST /oauth/approve — 多步骤登录（凭据 → 可选 OTP → 活动/商户选择器）

• POST /token — 交换 code / refresh

• POST|GET|DELETE /mcp — MCP Streamable HTTP（Bearer OAuth）

OAuth 登录所使用的 Laravel API：

• POST /onzecrm/v2/auth/login

• POST /onzecrm/v2/auth/verify-otp / resend-otp

• POST /onzecrm/v2/auth/scoped-comercios / select-scope

• POST /onzecrm/v2/auth/refresh / revoke

Docker

cp .env.example .env   # completar WIBI_BASE_URL, WIBI_API_KEY, WIBI_PUBLIC_URL
docker compose up -d --build
curl http://127.0.0.1:3939/healthz

DNS / 证书

所需操作（由拥有 DonWeb 访问权限的人员执行）： 创建 DNS 记录：

DNS 就绪后，我可以：

1. 签发 Let's Encrypt 证书（certbot --apache -d mcp.wibi.com.ar）

2. 创建专用虚拟主机，将整个根路径代理到容器（127.0.0.1:3939）

3. 将 WIBI_PUBLIC_URL 改为 https://mcp.wibi.com.ar 并重建容器

4. 从 wibi.com.ar 虚拟主机中移除临时的 OAuth ProxyPass 规则（/authorize、/token、/register 等）

当前临时方案（仅测试）： OAuth 通过 https://wibi.com.ar 发布，使用现有商业证书，将 OAuth 路由 + /mcp 代理到容器。这不是最终设计。

说明：

• DCR 客户端 + OAuth 令牌 + WibiSession 持久化存储在 Redis 中（Docker 中为 OAUTH_STORE=redis）。MCP 传输仍保留在进程内存中。

• 当前为单副本；Redis 为多副本铺平了道路。重新创建后不应再要求重新连接 Claude。

• 必须使用 HTTPS（凭据通过表单传输）。

• 网关从不存储商户的用户名/密码；仅存储短期 JWT + 不透明的 refresh 令牌（生产环境中存于 Redis）。

会话架构

claude.ai → OAuth (login comercio o admin) → access token MCP
         → /mcp (Bearer) → WibiClient con JWT del comercio
         → API v2 Laravel (scope por IdComercio / IdRed / idCampania)

当面板管理员登录时，最终 JWT 仍属于所选商户（与 v2 范围相同）。真实操作者（actor_id / actor_name / actor_role）会随 JWT 传递，并写入审计日志。

当 WIBI JWT 即将过期时，网关会通过 POST /onzecrm/v2/auth/refresh 续期（无需重新输入密码）。

同一会话内切换商户（仅限管理员）： 管理员/超级管理员无需重新登录或再次通过 2FA，即可使用工具 wibi_buscar_campanias、wibi_comercios_de_campania 和 wibi_cambiar_comercio（见下文）切换商户。内部会调用 POST /onzecrm/v2/auth/my-campanias、POST /onzecrm/v2/auth/my-scoped-comercios 和 POST /onzecrm/v2/auth/switch-scope（均使用当前令牌的 Bearer）；前两个仅查询，第三个会重新签发 JWT + refresh，同时保留真实的 actor_id 用于审计。直接商户登录（无操作者）看不到这些工具。

为什么存在 wibi_buscar_campanias： wibi_mis_campanias 仅返回与当前商户网络关联的活动（通常只有一个），而非管理员的完整范围。超级管理员可能有权访问数百个活动，且不知道它们的 ID。wibi_buscar_campanias 允许用户让 Claude“切换到活动 X”，按名称操作，而无需提前知道 idCampania。

主要工具

• 报告：交易、客户、产品、分类器、品牌、细分、标签、优惠券

• 行为：客户摘要、客户分析

• 群发：标签、WhatsApp 模板、计划/查询

• 订阅：警报类型、创建/查询

• 在 OAuth 模式下：wibi_mis_campanias

• 在 OAuth 模式下，仅限管理员会话（wibi_mis_campanias 中 es_admin: true）：wibi_buscar_campanias（在管理员范围内按名称搜索活动，无需知道 idCampania）、wibi_comercios_de_campania（列出管理员范围内某活动的商户）和 wibi_cambiar_comercio（无需重新登录即可切换会话的当前商户/活动）

电子邮件模板工具已禁用，直到对应的 Laravel 端点可用。

安全

• 按商户隔离：每个 MCP 会话都绑定到 OAuth sessionId + 登录时的 IdComercio。

• Laravel 中的写入操作会根据令牌范围验证客户/标签/警报。

• /oauth/approve 和 /mcp 上设有速率限制。

• 登录页面设置 Cache-Control: no-store、X-Frame-Options: DENY 和 CSP。