quark-mcp

Der Quark MCP Server bietet über die in den Quark-Browser integrierte KI-Chatseite (quark.cn/chat, Qwen) Funktionen für Bildanalyse, Fragen und Antworten sowie Text-zu-Bild-Generierung – ganz ohne API-Kosten.

Basierend auf CDP + Playwright wird ein Quark-Browser mit eigenem Profil übernommen; in der Chatseite werden Bilder hochgeladen, um Fragen zu stellen, und die Antworten werden abgeholt und zurückgegeben – kein API-Key erforderlich.

Fähigkeiten

Related MCP server: Percepta MCP Server

Funktionsweise

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

• Quark wird mit --remote-debugging-port=9224 und eigenem Profil gestartet, der Anmeldezustand ist persistent

• Bilder werden per DataTransfer injiziert (JS_DROP_IMAGE) und nicht über den Dateiauswahl-Dialog; gesendet wird, sobald die Anhangliste erscheint

• Abschlusskriterium einer Antwort: In einer Karte des Bereichs [data-chat-answers-wrap] erscheint das Waren die Klasse completed

Umgebungsanforderungen

• Python 3.10+

• Quark-Browser (automatische Erkennung über die Umgebungsvariable QUARK_PATH oder übliche Installationspfade)

• video_analyze benötigt ffmpeg/ffprobe (Frames extrahieren) plus pillow (Zeitstempel einbrennen, Bilder zusammensetzen)

• Optional: yt-dlp (Online-Videos herunterladen) sowie faster-whisper (Audio-Transkription, transcribe=True)

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）

Der mit pip installierte yt-dlp.exe liegt häufig in Scripts/ und nicht direkt im PATH aufgelistet. Der Code hat dafür bereits einen Rückfall eingebaut: Wird der Befehl yt-dlp nicht gefunden, wird automatisch python -m yt_dlp verwendet – funktioniert also auch ohne PATH-Konfiguration.

Verwendung

1. Als MCP-Server (mit Claude Code usw.)

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

2. HTTP-Modus (Debugging)

python server.py --port 8080

3. Direkter CLI-Aufruf (ohne 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

Hinweise zur Bildgenerierung

• Modell: Folgt der Voreinstellung der Chatseite (Qwen), nicht wählbar

• Auslösung: Es gibt keinen eigenen Schalter für „Bildgenerierung“; die Auslösung erfolgt über natürliche Sprache (im Prompt präzise beschreiben, was erzeugt werden soll)

• Seitenverhältnis: Die Webversion hat keinen Seitenverhältnis-Auswahlregler, dies muss im Prompt beschrieben werden (z. B. „16:9 Querformat“)

• Ergebnis: Pro Durchlauf ca. 4 Bilder, getestet ungefähr 960×1280

• Download: Die CDN-URLs besitzen eine auth_key-Signatur; sie müssen über den Browser-Kontext (page.request) abgerufen werden – ein direkter urllib-Aufruf führt zu 4logout0.

# 返回结构
{"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": "千问(夸克对话页默认)"}}

Konfiguration

• Quark-Pfad: Setzen Sie die Umgebungsvariable QUARK_PATH, um das ausführbare Programm zu bestimmen

• CDP-Port: Standardwert 9224, siehe CDP_PORT in quark_ai.py (abweichend von 9223 des doubao-mcp, beide können koexistieren)

• Anmeldezustand: Das normale eigene Profi befindet sich unter ~/.claude/quark-Pizza-cream; nach dem ersten daemon_start genügt eine manuelle Anmeldung

• Bildverzeichnis: Standardmäßig ~/.claude/quark-images, mit outdir überschreibbar

Häufig gestellte Fragen

• Exit-Code 1 (CDP nicht erreichbar bzw. Quark nicht gefunden): Daemon nicht gestartet, zuerst daemon_start ausführen; oder QUARK_PATH setzen

• Exit-Code 2 (nicht angemeldet): Chatseite öffnen und einmal manuell anmelden

• Exit-Code 3 (Bildproblem): Der Pfad existiert nicht oder der Upload ist fehlgeschlagen

• Exit-Code 4 (Interaktionsfehler): Eingabefeld- oder Sende-Button nicht gefunden, meist nach einem Seiten-Update

• Exit-Code 5 (Timeout): Generierung dauert zu lange; den timeout erhöhen (Standard bei Bildern: 300 s)

• Exit-Code 6 (Ergebnis leer): Antwort ist leer oder es wurde kein Bild erzeugt – möglicherweise Risiko-Brutalismus oder Inhalt wurde gefiltert

Abhängigkeit von der Seitenstruktur

Interne Web-Eingriffe bedeuten, dass eine Quark-SeitenauEine Delegation kann bereits die Funktion zerstören. Die aktuell getestete Abhängigkeit (SEL in quark_ai.py, basierend auf Quark 7.1.2.956 / Kombination 144 + Web-Version 4.0.0):

Zwei Fallstricke:

1. Das Fertigzeichnen ist das completed der Antwortkarte, nicht das qcenter auf dem .markdown – ein qk-markdown-complete ist die Stellen konnte im Client-Panel geschrieben, bei der Web-Version gibt es das nicht. Ein Übernehmen davon führt dazu, dass immer der Status „nicht fertig“ erscheint.

2. Bei der Bildgenerierung muss man warten, bis der Satz von signierten Bild-URLs stabil ist; es genügt nicht, nur auf completed zu undreißen. Text bekommt zuerst completedba, aber das eigentliche Bild braucht noch ca. 45 s, bis die Platzhalter-Animation ersetzt wird. Wenn nach dem completed-Text sowie weiterem IMAGE_GROSSE (120 s) immer noch kein Bild vorhanden ist, wird erst dann entschlossen, dass diese Runde kein Bild erzeugt.

Lizenz

MIT