quark-mcp

El servidor MCP de Quark ofrece capacidades visuales, de preguntas/respuestas y de generación de texto a imagen sin coste de API a través del chat de IA integrado en el navegador Quark (quark.cn/chat, 千问).

Basado en CDP + Playwright, toma el control del navegador Quark con un perfil independiente, sube imágenes en la página de chat, pregunta y recupera las respuestas. No requiere API Key.

Capacidades

Related MCP server: Percepta MCP Server

Cómo funciona

Claude Code ──MCP stdio──> server.py ──> quark_mcp/quark_ai.py ──CDP──> 夸克浏览器（独立 profile）
                                         quark_mcp/video_analyze.py         │
                                                                  quark.cn/chat（网页版千问）

• Quark se inicia con --remote-debugging-port=9224 y un perfil independiente; el estado de sesión persiste.

• Las imágenes se inyectan mediante DataTransfer (JS_DROP_IMAGE) en lugar de usar un filechooser; espera a que aparezca la lista de adjuntos antes de enviar.

• Criterio de finalización de la respuesta: en la ronda de respuestas de la IA, la tarjeta [data-chat-answers-wrap] contiene la clase completed.

Requisitos del entorno

• Python 3.10+

• Navegador Quark (detecta automáticamente la variable de entorno QUARK_PATH o rutas comunes de instalación)

• video_analyze requiere ffmpeg/ffprobe (extracción de fotogramas) y pillow (marcas de hora, imagen mosaico)

• Opcional: yt-dlp (para descargar videos online) y faster-whisper (transcribe=True para transcribir audio)

Instalación

pip install fastmcp playwright websocket-client
# 可选功能依赖
pip install pillow           # 视频帧时间戳烧录 + 拼图（video_analyze 必需）
pip install yt-dlp           # 在线视频下载（video_analyze 传 URL 时）
pip install faster-whisper   # 音频转写（transcribe=True）

El yt-dlp.exe instalado con pip normalmente queda en Scripts/ y no está en el PATH; el código ya incluye una alternativa: si no se encuentra el comando yt-dlp, usa automáticamente python -m yt_dlp. Por lo tanto, funciona incluso sin configurar el PATH.

Uso

1. Como servidor MCP (Claude Code, etc.)

{
  "mcpServers": {
    "quark-mcp": {
      "command": "python",
      "args": ["/path/to/quark-mcp/server.py"]
    }
  }
}

2. Modo HTTP (para depurar)

python server.py --port 8080

3. Llamada directa por CLI (sin MCP)

# 启动 daemon（首次需手动登录一次，登录态持久化）
python quark_mcp/quark_ai.py --start
python quark_mcp/quark_ai.py --status

# 纯文本问答
python quark_mcp/quark_ai.py --ask "帮我解释一下 CDP 是什么"

# 图片识别
python quark_mcp/quark_ai.py --image photo.jpg --question "请描述这张图片"

# 文生图（默认存 ~/.claude/quark-images）
python quark_mcp/quark_ai.py --gen "一只橘猫坐在窗台看夕阳,插画风格"
python quark_mcp/quark_ai.py --gen "复古黄铜怀表" --outdir ./imgs --max-images 2

# 视频分析（本地文件或 URL）
python quark_mcp/video_analyze.py --video demo.mp4
python quark_mcp/video_analyze.py --video demo.mp4 --transcribe

Notas sobre generación de imágenes

• Modelo: sigue el predeterminado de la página de chat de Quark (千问), no se puede especificar otro.

• Activación: no hay un interruptor específico de «generación de imágenes»; se activa mediante lenguaje natural (deja claro en el prompt qué dibujar).

• Proporción: la versión web no tiene selector de proporciones; hay que indicarlo por texto (por ejemplo, «16:9 apaisado»).

• Resultado: suele generar unas 4 imágenes por vez; en pruebas reales, alrededor de 960×1280.

• Descarga: las URLs del CDN están firmadas con auth_key; es obligatorio usar el contexto del navegador (page.request) para obtener las imágenes, ya que usar urllib directamente da 403.

# 返回结构
{"ok": True,
 "images": ["C:/Users/.../.claude/quark-images/quark_20260823-103519_1.png", ...],
 "text": "已生成 2 张图片, 保存至 ...",
 "meta": {"found": 4, "details": [{"path": ..., "bytes": ..., "width": 960, "height": 1280}],
          "model": "千问(夸克对话页默认)"}}

Configuración

• Ruta de Quark: define la variable de entorno QUARK_PATH para indicar el ejecutable.

• Puerto CDP: por defecto 9224; consultar CDP_PORT en quark_ai.py (separado del 9223 de doubao-mcp para que puedan coexistir).

• Sesión de acceso: el perfil independiente se guarda en ~/.claude/quark-ai-profile. Después del primer daemon_start, basta con iniciar sesión manualmente una vez.

• Directorio de imágenes: por defecto ~/.claude/quark-images, se puede sobreescribir con outdir.

Preguntas frecuentes

• Código de salida 1 (CDP inaccesible / no se encuentra Quark): el daemon no está iniciado; primero ejecuta daemon_en marcha; o define QUARK_PATH.

• Código de salida 2 (sin acceso): abre la página de chat e inicia sesión manualmente una vez.

• Código de salida 3 (problema con la imagen): la ruta no existe o la subida falló.

• Código de salida 4 (fallo de interacción): no se encontró el campo de entrada o el botón de envío; suele ser por cambios en la página.

• Código de salida 5 (timeout): la generación es lenta; aumenta timeout (300s por defecto para imágenes).

• Código de salida 6 (resultado vacío): la respuesta vacía o no se produjo ninguna imagen; puede deberse a control de riesgos o filtrado de contenido.

Dependencia de la estructura de la página

Al manipular la página directamente, un rediseño de Quark puede hacer que deje de funcionar. Dependencias actualmente probadas (en SEL de quark_ai.py, basadas en Quark 7.1.2.956 / Chromium 144 + versión web 4.0.0):

Dos trampas:

1. El indicador de completado es completed en la tarjeta de respuesta, no qk-markdown-complete dentro de .qk-markdown — este último solo se usa en paneles del cliente; la versión web no lo tiene, así que usarlo hará que nunca se considere «completado».

2. Para generar imágenes, hay que esperar a que el «conjunto de URLs firmadas de imágenes» sea estable y no puede basarse solo en completed — el texto aparece como completed primero, pero la imagen final tarda unos 45 s más en reemplazar la animación de marca de lugar. Después de que el texto esté completed, se espera IMAGE_GRACE (120 s) y, si aún no hay imagen, se concluye que esta ronda no produce imágenes.

Licencia

MIT