quark-mcp

夸克 MCP Server — 夸克浏览器内建 AI 对话页面（quark.cn/chat，千问）을 통해 API 비용 0원의 비전, 질의응답, 텍스트-이미지 생성 기능을 제공합니다.

CDP + Playwright로 독립 profile의 夸克 브라우저를 제어하며, 대화 페이지에 이미지를 업로드하고 질문한 뒤 응답을 크롤링해 반환합니다. API Key가 필요 없습니다.

기능

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으로 독립 profile을 시작하며 로그인 상태는 유지됩니다.

• 이미지는 filechooser 대신 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 server로 사용(Claude Code 등)

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

2. HTTP 모드(디버깅)

python server.py --port 8080

3. MCP 없이 CLI 직접 호출

# 启动 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

이미지 생성 설명

• 모델: 夸克 대화 페이지 기본(千问)에 따르며 변경 불가

• 트리거: 별도의 「이미지 생성」 기술 스위치는 없으며, 자연어로 트리거됩니다(prompt에 지시하는 내용을 명확히 작성).

• 비율: 웹 버전에 비율 선택 기능이 없으며, prompt에 문자로 표시해야 합니다(예: 「16:9 가로 구도」).

• 결과: 한 번에 약 4장 생성, 실제 측정 결과 약 960×1280 정도입니다.

• 다운로드: CDN URL에 auth_key 서명이 있어 반드시 브라우저 context(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과 분리되어 함께 사용 가능).

• 로그인 상태 : 독립 profile은 ~/.claude/quark-ai-profile에 있으며, 처음 daemon_start 후 한 번 수동 로그인하면 됩니다.

• 출력 이미지 디렉터리: 기본값은 ~/.claude/quark-images이며, outdir로 덮어쓸 수 있습니다.

자주 묻는 질문

• 출력 코드 1 (CDP 접근 불가 / 夸克 없음): daemon이 실행되지 않음, daemon_start 우선 실행; 또는 QUARK_PATH 설정.

• 출력 코드 2 (로그인 안 됨): 대화 페이지를 열고 한 번 수동으로 로그인.

• 출력 코드 3 (이미지 문제): 경로가 존재하지 않거나 업로드 실패.

• 출력 코드 4 (상호작용 실패): 입력 상자/전송 버튼 없음, 대부분 페이지 개편 문제.

• 출력 코드 5 (시간 초과): 생성이 느림, timeout 크게 늘리기(이미지 생성 기본값 300초).

• 출력 코드 6 (결과 비었음): 응답이 비었거나 이미지가 생성되지 않음, 리스크 규제 또는 콘텐츠 필터링일 수 있음.

페이지 구조 의존성

순수 웹 조작이기 때문에 夸克 개편과 함께 잘못될 수 있습니다. 현재 기준으로 확인된 의존성(quark_ai.py의 SEL, 夸克 7.1.2.956 / Chromium 144 + 웹 4.0.0 기준):

주의할 점 2가지:

1. 완료 표시는 응답 카드의 완료 클래스에 있습니다. .qk-markdown의 qk-markdown-complete와는 다릅니다 — 후자는 챗 UI의 방식으로, HTML 웹 버전에는 없고, 그 대로 쓰면 항상 「미완료」로 판정됩니다.

2. 이미지 생성은 "서명된 이미지 URL 집합이 안정될 때"까지 기다려야 하며, completed 하나만 보고 판단해선 안 됩니다. 텍스트 답변은 먼저 completed로 표시되고, 최종 이미지는 약 45초 더 지나서 placeholder 이미지가 교체됩니다. 텍스트 completed 후 IMAGE_GRACE(120초) 동안 기다려도 이미지가 없으면 그 턴은 이미지가 생성되지 않는 것으로 판단합니다.

License

MIT