xingzi-mcp

Servidor MCP para Xingzi — Deja que la IA te ayude a publicar materiales, revisar recibos y realizar pagos.

Índice

• ¿Qué es la distribución de material?

• Flujo de trabajo

• Instalación y configuración

• Herramientas disponibles

• Ejemplos de uso

• Referencia de precios

• Guía para redactar requisitos de tareas

• Arquitectura técnica

• Notas de ingeniería inversa de la API

• FAQ

• Changelog

¿Qué es la distribución de material?

La "distribución de material" es un modelo de promoción KOC (Key Opinion Consumer):

• Anunciante (tú): Tienes necesidades de promoción, preparas el material (imágenes/vídeos/copy) y estás dispuesto a pagar por resultados.

• KOC (Creador): Tiene cuentas en varias plataformas sociales y está dispuesto a ayudarte a publicar contenido para ganar recompensas.

• Plataforma Xingzi: La plataforma intermedia que conecta a ambas partes, proporcionando capacidades para publicar tareas, reclamarlas, enviar recibos y realizar pagos.

Este servicio MCP sirve al rol de "Anunciante": publicar tareas, auditar recibos y pagar a los KOC.

Flujo de trabajo

┌─────────────────────────────────────────────────────────┐
│                    广告主（你 + AI）                       │
│                                                         │
│  ① publish_task ──→ 发布任务（素材+要求+单价+人数）        │
│                         │                                │
│                         ▼                                │
│              KOC 在素材广场看到并领取                       │
│                         │                                │
│                         ▼                                │
│              KOC 发布到社交媒体，提交回执                   │
│                         │                                │
│  ③ list_postbacks ──→ 查看回执                            │
│                         │                                │
│  ④ audit_postback ──→ 审核（通过/拒绝）                    │
│                         │                                │
│  ⑤ pay_reward ──────→ 生成支付链接                        │
│                         │                                │
│                         ▼                                │
│              在微信中打开链接完成付款 ✅                     │
└─────────────────────────────────────────────────────────┘

Instalación y configuración

Requisitos previos

• Node.js >= 18

• Una herramienta de IA compatible con MCP (Claude Code / Cursor / Windsurf / Cline, etc.)

• Una cuenta en la plataforma Xingzi Zhutui (Registro: https://m.xingziwenhua.com )

• Membresía Xingzi (VIP): Se requiere ser miembro para publicar tareas de distribución de material (ver explicación abajo).

¿Por qué se necesita la membresía? La plataforma Xingzi Zhutui exige que solo los miembros puedan publicar tareas de distribución de material, esto se debe a dos razones:

1. Crédito y cumplimiento: El sistema de membresía ayuda a la plataforma a controlar los riesgos de crédito y de incumplimiento, asegurando que los anunciantes tengan la capacidad de pagar a tiempo.

2. Beneficios de membresía: La distribución de material es un servicio exclusivo de valor añadido para los miembros de la plataforma.

Si aún no eres miembro, puedes activarlo en el "Centro de Membresía" de la App / H5 de Xingzi Zhutui.

Claude Code

Edita ~/.claude/settings.json:

{
  "mcpServers": {
    "xingzi": {
      "command": "npx",
      "args": ["-y", "xingzi-mcp"],
      "env": {
        "XINGZI_MOBILE": "你的手机号",
        "XINGZI_PASSWORD": "你的密码"
      }
    }
  }
}

Cursor

Edita .cursor/mcp.json:

{
  "mcpServers": {
    "xingzi": {
      "command": "npx",
      "args": ["-y", "xingzi-mcp"],
      "env": {
        "XINGZI_MOBILE": "你的手机号",
        "XINGZI_PASSWORD": "你的密码"
      }
    }
  }
}

Windsurf / Otros

Simplemente añade la misma configuración en el archivo de configuración MCP de la herramienta correspondiente.

Sin configurar variables de entorno (Inicio de sesión manual)

También puedes dejar el campo env vacío y, al usarlo por primera vez, pedirle a la IA que llame a la herramienta login:

"Ayúdame a iniciar sesión en Xingzi, número de teléfono 138xxxx, contraseña xxxx"

Herramientas disponibles

Hay 11 herramientas en total, que cubren todo el flujo de trabajo del anunciante:

Autenticación y guía

Publicación de tareas

Auditoría de recibos

Pagos

Billetera

Ejemplos de uso

Publicar una tarea de distribución

你：帮我发一个代发任务
    素材是这张图 https://example.com/ad.jpg
    要求发到小红书，配文提到"夏日好物推荐"
    单价10元，最多50人

AI：[调用 publish_task]
    ✅ 任务发布成功！50 个名额，10 元/条。
    KOC 可以在素材广场看到并领取。

Auditar recibos y realizar pagos

你：看看任务 1615 的回执，合格的帮我通过

AI：[调用 list_postbacks] 共 3 条回执
    - 66°C 提交了抖音链接 ✓
    - 小明 提交了小红书截图 ✓  
    - 用户A 截图模糊看不清 ✗

    [调用 audit_postback x3] 通过 2 条，拒绝 1 条

你：帮我打款

AI：[调用 pay_reward]
    待打款 2 人，共 20 元
    请在微信中打开此链接付款：https://m.xingziwenhua.com/spages/material/batchpay?id=1615
    
    💡 支付页面可以修改金额（表现好的可以加钱），也可以写奖励说明。

Ver billetera

你：钱包余额多少？

AI：[调用 get_wallet]
    总收益：11,290.36 元
    可提现：11,256.46 元
    已提现：33.90 元
    冻结中：0.00 元

Referencia de precios

Las tareas con un precio inferior a 5 yuanes tienen una tasa de aceptación muy baja, el MCP te lo recordará activamente.

Guía para redactar requisitos de tareas

Los requisitos de la tarea (task_requirement) son clave para la tasa de aceptación y la calidad de la finalización.

Ejemplo de buenos requisitos de tarea

发布到小红书，图文形式。
配文需包含"XXX品牌夏日新品"关键词，200字以内。
发布后截图+笔记链接作为回执。

发布到抖音，直接使用我提供的视频素材。
视频标题和文案自由发挥，需要 @XXX品牌 官方账号。
发布后提交视频链接。

Se recomienda incluir

• En qué plataforma publicar (Xiaohongshu / Douyin / Zhihu / Weibo, etc.)

• Formato (Imagen/Texto / Vídeo / Artículo)

• Puntos clave del copy (nombre de marca, palabras clave, hashtags, etc.)

• Requisitos de tiempo de publicación (si los hay)

Se recomienda evitar

• ❌ Pedir publicar en múltiples plataformas a la vez (es mejor dividirlo en varias tareas)

• ❌ Limitar el número de seguidores (a menos que estés dispuesto a aumentar significativamente el precio unitario)

• ❌ Requerir vídeos largos originales (alta complejidad, baja tasa de finalización)

• ❌ Requerir fijar/destacar/hacer viral (factores incontrolables)

• ❌ Descripción de la tarea demasiado larga o compleja (los KOC se irán al verla)

Arquitectura técnica

Diseño general

┌──────────────────┐     stdio      ┌───────────────────┐
│  AI 工具          │ ◄──────────► │  xingzi-mcp       │
│  (Claude/Cursor)  │   MCP协议     │  (Node.js Server) │
└──────────────────┘               └─────────┬─────────┘
                                             │ HTTPS
                                             ▼
                                   ┌───────────────────┐
                                   │  api.xingziwenhua  │
                                   │  .com              │
                                   │  (星子助推后端)      │
                                   └───────────────────┘

Stack tecnológico

• Runtime: Node.js >= 18 (usando fetch nativo)

• MCP SDK: @modelcontextprotocol/sdk

• Validación de parámetros: zod (dependencia integrada en MCP SDK)

• Protocolo de transporte: stdio (entrada/salida estándar)

• Comunicación API: HTTPS REST, formato JSON

Mecanismo de autenticación

La API de Xingzi utiliza un método de autenticación no estándar (descubierto mediante ingeniería inversa de la aplicación H5):

// 不是标准的 Authorization: Bearer <token>
// 而是三个自定义 HTTP headers:
headers: {
  "token": "<JWT>",      // 登录返回的 token
  "plt": "h5",           // 平台标识，固定值
  "user_id": "<number>"  // 用户 ID
}

El token tiene una validez de 24 horas; el MCP volverá a iniciar sesión automáticamente antes de que caduque.

Procesamiento de montos

La API utiliza internamente centavos como unidad monetaria (ej. 500 = 5.00 yuanes). El MCP utiliza uniformemente yuanes y realiza la conversión automáticamente.

Proceso de pago

Los pagos se realizan mediante pago WeChat JSAPI, lo que requiere un entorno de navegador WeChat (WeixinJSBridge). El MCP no puede iniciar el pago directamente, por lo que genera una URL de página de pago:

https://m.xingziwenhua.com/spages/material/batchpay?id={task_id}
https://m.xingziwenhua.com/spages/material/batchpay?id={task_id}&to_user_id={koc_id}

El usuario puede completar el pago abriendo el enlace en WeChat. La página de pago permite modificar el monto y completar la descripción de la recompensa.

Notas de ingeniería inversa de la API

Todos los endpoints de la API de este MCP se obtuvieron mediante ingeniería inversa de la aplicación H5 de Xingzi Zhutui (m.xingziwenhua.com); la plataforma no proporciona documentación oficial de la API.

Método de ingeniería inversa

1. Puppeteer para simular un navegador móvil y acceder a la aplicación H5.

2. Interceptar peticiones XHR para observar las llamadas a la API (cabeceras personalizadas en lugar de autenticación Bearer estándar).

3. Analizar el JS de los chunks de webpack para extraer todas las rutas de la API.

4. Probar cada endpoint para confirmar parámetros y formatos de respuesta.

Hallazgos clave

Endpoints de API verificados

POST /c/user/login                               — 手机号+密码登录
GET  /c/user/detail                              — 用户信息
GET  /c/channel/list-available                   — 可用推广频道
POST /c/fodder/material/instead/publish           — 发布素材任务
GET  /c/fodder/material/instead/list              — 素材列表
GET  /c/fodder/material/instead/materialInfo      — 素材详情
POST /c/fodder/material/instead/del               — 删除素材
GET  /c/fodder/material/instead/postback/list     — 回执列表
POST /c/fodder/material/instead/postbackAudit     — 审核回执
GET  /c/fodder/material/instead/unpaidAward/list  — 待打款列表
POST /c/fodder/material/instead/batch/pay/reward  — 批量打款 (需微信)
GET  /c/withdraw/wallet                          — 钱包余额

Códigos de estado de recibo (status)

FAQ

P: ¿Cómo se cargan los archivos de material?

publish_task de MCP recibe una URL de archivo (enlace accesible públicamente), no una ruta de archivo local. Debes cargar el archivo primero en cualquier servicio de alojamiento de archivos (como Tencent Cloud COS, Alibaba Cloud OSS, Qiniu, o incluso GitHub) y luego pasar la URL al MCP.

La aplicación H5 de Xingzi realiza la carga directa frontal a Tencent Cloud COS, pero la interfaz de carga está vinculada al SDK frontal y no se puede llamar a través de una API pura.

P: ¿Por qué el pago no se puede completar directamente en el MCP?

El pago de Xingzi utiliza WeChat JSAPI, que requiere llamar a WeixinJSBridge.invoke('getBrandWCPayRequest', ...) dentro del navegador WeChat. Esta es una limitación técnica de WeChat Pay, no del MCP. El MCP generará un enlace a la página de pago que puedes abrir en WeChat para pagar.

P: ¿Se pueden enviar múltiples archivos de material en una tarea?

Sí. El parámetro files es una matriz que admite múltiples URL, hasta 50 archivos. Formatos admitidos: gif, jpg, jpeg, png, word, txt, pdf, mp4.

P: ¿Qué sucede con el material después de que se rechaza una auditoría?

Después del rechazo, la cuota de reclamación de ese KOC se libera y otros KOC pueden seguir reclamándola. Si completaste el motivo del rechazo (reject_reason), el KOC también podrá verlo.

P: ¿Qué pasa si el token caduca?

No te preocupes. El MCP volverá a iniciar sesión automáticamente con tu nombre de usuario y contraseña antes de que el token caduque. El token tiene una validez de 24 horas.

P: ¿Se pueden usar varias cuentas al mismo tiempo?

Una instancia de MCP corresponde a una cuenta. Si necesitas varias cuentas, puedes añadir varios servidores en la configuración de MCP, distinguiéndolos con diferentes nombres:

{
  "mcpServers": {
    "xingzi-account1": {
      "command": "npx",
      "args": ["-y", "xingzi-mcp"],
      "env": { "XINGZI_MOBILE": "手机号1", "XINGZI_PASSWORD": "密码1" }
    },
    "xingzi-account2": {
      "command": "npx",
      "args": ["-y", "xingzi-mcp"],
      "env": { "XINGZI_MOBILE": "手机号2", "XINGZI_PASSWORD": "密码2" }
    }
  }
}

P: ¿Cuál es el precio unitario adecuado?

Depende de la complejidad de la tarea. Se sugieren al menos 5 yuanes; por debajo de 5 yuanes, casi nadie la reclamará. Ver Referencia de precios.

P: ¿Se puede cambiar el monto en la página de pago?

Sí. Después de abrir el enlace generado por pay_reward, el monto de cada KOC se puede modificar manualmente. Por ejemplo, si un KOC tiene una calidad especialmente buena, puedes pagarle más. También puedes completar una "descripción de recompensa" que el KOC podrá ver.

P: ¿Qué relación tiene este MCP con la App Xingzi Zhutui?

Xingzi Zhutui es una plataforma completa de promoción KOC que incluye diversas actividades promocionales como tweets, miniseries, novelas, etc. La "distribución de material" es un módulo de producto independiente. Este MCP solo encapsula las operaciones del anunciante para la distribución de material y no incluye otras funciones de Xingzi Zhutui (palabras clave, gestión de equipos, estadísticas de ingresos, etc.).

P: ¿Es seguro? ¿Dónde se guarda la contraseña de la cuenta?

• Método de variables de entorno: La contraseña se guarda en el archivo de configuración MCP de tu máquina local y no se transmite a ningún lugar fuera de la API de Xingzi.

• Método de inicio de sesión manual: La contraseña solo se utiliza durante la sesión actual.

• El código MCP es completamente de código abierto y puedes auditarlo tú mismo.

Changelog

3.0.0 (2026-04-06)

• Verificación completa del flujo de extremo a extremo.

• Limpieza completa de código y documentación.

• Publicación en GitHub.

2.1.0

• pay_reward admite pagos individuales/totales, admite el parámetro koc_user_id.

• El enlace de pago admite filtrado por to_user_id.

2.0.1

• Corrección del parámetro audit_postback: is_pass (no isPass), claim_id + postback_id (no material_id + id).

2.0.0

• Refactorizado para ser exclusivo de distribución de material, eliminando funciones irrelevantes de Xingzi Zhutui.

• Herramientas reducidas de 21 a 11.

• Optimización de valores predeterminados: canal fijo de distribución de material, material convencional, precio unitario fijo, visibilidad pública.

• Unidad monetaria cambiada de "centavos" a "yuanes".

• Nueva herramienta de guía de uso guide.

1.0.0

• Versión inicial, incluye encapsulación completa de la API de Xingzi Zhutui.

Licencia

MIT