quark-mcp

Quark MCP Server — provides zero API cost vision, Q&A, and text-to-image capabilities through the AI conversation page built into the Quark browser (quark.cn/chat, Qwen).

Drives a dedicated-profile Quark browser via CDP + Playwright, uploads an image to the conversation page to ask questions, captures the reply, and returns it. No API key required.

Capabilities

Related MCP server: Percepta MCP Server

How it works

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

• Quark is launched with --remote-debugging-port=9224 using a dedicated profile; the login state is persisted

• Images are injected via DataTransfer (JS_DROP_IMAGE) instead of a file chooser, and sending happens after the attachment list appears

• Reply completion criterion: the card class within [data-chat-answers-wrap] for an AI reply turn contains completed

Requirements

• Python 3.10+

• Quark browser (auto-detects the QUARK_PATH environment variable or common install paths)

• video_analyze requires ffmpeg/ffprobe (frame extraction) and pillow (burn timestamps, create tile grid)

• Optional: yt-dlp (online video download), faster-whisper (transcribe=True audio transcription)

Installation

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

The yt-dlp.exe installed via pip often lands in Scripts/ and is not on PATH; the code has a fallback: if the yt-dlp command is not found, it automatically uses python -m yt_dlp, so it works without configuring PATH.

Usage

1. As an MCP server (Claude Code, etc.)

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

2. HTTP mode (for debugging)

python server.py --port 8080

3. Direct CLI invocation (without 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

Image generation notes

• Model: follows the Quark conversation page default (Qwen); cannot be specified

• Trigger: there is no separate "image generation" capability switch; it is triggered by natural language (describe in the prompt what should be drawn)

• Aspect ratio: the web version has no aspect ratio selector; describe it in the prompt as text (e.g. "16:9 landscape")

• Output: about 4 images per run, measured around 960×1280

• Download: CDN URLs are signed with auth_key, so images must be fetched through the browser context (page.request); bare urllib returns 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": "千问(夸克对话页默认)"}}

Configuration

• Quark path: set the QUARK_PATH environment variable to specify the executable

• CDP port: defaults to 9224, see CDP_PORT in quark_ai.py (kept distinct from doubao-mcp's 9223, so they can coexist)

• Login state: the dedicated profile is at ~/.claude/quark-ai-profile; after the first daemon_start, log in manually once

• Image output directory: defaults to ~/.claude/quark-images, overridable with outdir

Common issues

• Exit code 1 (CDP unreachable / Quark not found): daemon not started; run daemon_start first, or set QUARK_PATH

• Exit code 2 (not logged in): open the conversation page and log in manually once

• Exit code 3 (image problem): the path does not exist or the upload failed

• Exit code 4 (interaction failed): the input box / send button was not found; usually a page redesign

• Exit code 5 (timeout): generation is slow; increase the timeout (image generation default 300s)

• Exit code 6 (empty result): the reply is empty or no image was produced; possibly risk control or filtered content

Page structure dependencies

Because this is pure web-page automation, a Quark redesign can break things. Currently verified dependencies (SEL in quark_ai.py, based on Quark 7.1.2.956 / Chromium 144 + web version 4.0.0):

Two gotchas:

1. The completion marker is completed on the reply card, not the .qk-markdown marker qk-markdown-complete — the latter is a client-side panel convention, and the web version doesn't have it, so copying it verbatim will always give a "not finished" result.

2. Text-to-image must wait for the "signed-image URL set to stabilize", not just for completed — the text reaches completed first, while the final image takes about another 45s to replace the placeholder animation. Only when the text is completed and then IMAGE_GRACE (120s) passes with no image does the round be considered as not producing an image.

License

MIT