quark-mcp

夸克 MCP Server — 夸克ブラウザ内蔵の AI 会話ページ（quark.cn/chat、千问）を経由して、ゼロ API コストでビジョン・Q&A・テキストから画像を生成する機能を提供します。

CDP + Playwright で独立したプロファイルの夸克ブラウザを操作し、会話ページで画像をアップロードして質問し、応答を取得して返します。API キーは不要です。

機能

Related MCP server: Percepta MCP Server

動作原理

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

• 夸克を --remote-debugging-port=9224 で起動し、独立プロファイルにするためログイン状態は永続化される

• 画像はファイルチューザーではなく DataTransfer 注入（JS_DROP_IMAGE）でアップロードし、添付リストが表示されてから送信する

• 回答完了の判定：AI の回答ターン [data-chat-answers-wrap] のカード class に completed が出たこと

環境要件

• Python 3.10+

• 夸克ブラウザ（QUARK_PATH 環境変数または一般的なインストール先を自動検出）

• video_analyze には ffmpeg/ffprobe（フレーム抽出）と pillow（タイムスタンプ焼き込み・タイル結合）が必要

• 任意：yt-dlp（オンライン動画のダウンロード）、faster-whisper（transcribe=True での音声文字起こし）

インストール

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

pip で入れた yt-dlp.exe は Scripts/ に入って PATH が通っていないことが多いが、コード側でフォールバック済み： yt-dlp コマンドが見つからないときは自動的に python -m yt_dlp を使うので、PATH を設定しなくても使えます。

使用

1. MCP サーバーとして使う（Claude Code など）

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

2. HTTP モード（デバッグ）

python server.py --port 8080

3. CLI から直接呼ぶ（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

画像生成について

• モデル：夸克の会話ページのデフォルト（千问）に従う。指定は不可

• トリガー方式：独立した「画像生成」スキルのオン/オフはなく、自然言語で（プロンプトに描きたい内容を明記して）トリガーする

• アスペクト比：Web版には比率の選択肢がないので、プロンプト内で言葉で指定する （例：「16:9 横构图」）

• 出力: 一度に約4枚、実測で 856×1280 前後

• ダウンロード：CDN URL が auth_key 署名を持つため、必ずブラウザコンテキスト（page.request）で画像を取得する。裸の urllib では 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": "千问(夸克对话页默认)"}}

設定

• 夸克のパス：環境変数 QUARK_PATH で実行ファイルを指定

• CDP ポート：デフォルトは 9224。quark_ai.py 内の CDP_PORT を参照（doubao-mcp の 9223 とは採番を分けてあり共存可能）

• ログイン状態: 独立プロファイルは ~/.claude/quark-ai-profile に置かれる。初回 daemon_start 後に一度だけ手動でログインすればよい

• 画像の出力先：デフォルトは ~/.claude/quark-images。outdir で上書きできる

よくある質問

• 終了コード1（CDP に到達できない／夸克が見つからない）: daemon が起動していない。先に daemon_start するか、QUARK_PATH を設定する

• 終了コード2（未ログイン）: 会話ページを開いて手動で一度ログインする

• 終了コード3（画像の問題）: パスが存在しないか、アップロードに失敗

• 終了コード4（操作の失敗）: 入力欄・送信ボタンが見つからない。たいていはページの改訂（リマイク）が原因

• 終了コード5（タイムアウト）: 生成が遅い。timeout を増やす（画像生成のデフォルトは 300秒）

• 終了コード6（結果が空）: 回答が空か、画像が出なかった。リスク制御（机制）やコンテンツのフィルタリングの可能性

ページ構造への依存

純Web操作である以上、夸克が変更されれば動かなくなる可能性がある。現時点で確認している（quark_ai.py の SEL、夸克 7.1.2.956 / Chromium 144 + Web版 4.0.0）：

落とし穴が 2 つあります：

1. 完了マーカーは質問カード上の completed であり、qk-markdown の qk-markdown-complete ではない——後者は「 Wolken 」クライアント側パネルの表記で、Web版には存在しない。それをそのまま真似ると永遠に「未完了」と誤判定する。

2. 画像生成は「署名付き画像 URL の集合が安定する」を待つ必要があり、completed だけでは判定できない——テキストが先に completed になって、完成画像はそこからさらに約45秒後にプレースホルダのアニメーションが差し替わる。テキストが completed になってから IMAGE_GRACE（120秒）待っても画像がない場合、その回では画像を生成しなかったと判定する。

License

MIT