豆包生图 MCP（doubao-image-mcp）

官网 / 下载页：https://haikuotianko.github.io/doubao-image-mcp/

把豆包网页版（doubao.com）的生图能力封装成本地 MCP 服务：不需要官方 API Key，用你自己的网页登录态直接调用，Seedream 4.0 / 4.5 / 5.0 全系可用。附带一个桌面端（Wails + WebView2），负责扫码登录、多账号管理、测试生图与排障。

Local MCP server that exposes Doubao's web image generation as tools for Claude Desktop / Cursor / any MCP client — no API key, just your own web session.

目录

• 它能做什么

• 环境要求

• 下载

• 版本与更新检查

• 安装

• 首次使用

• 接入 MCP 客户端

• 工具参考

• 多账号与自动排队

• 会话复用与上下文隔离

• 数据位置

• 排障

• 已知限制

• 跨平台说明

• 开发

Related MCP server: Higgsfield Unlimited MCP

它能做什么

MCP 对外提供 6 个工具：

doubao_login 的关键点：stdio 模式下 MCP 进程同样跑在你的桌面会话里，所以它能直接开一个 WebView2 扫码窗口（最多等 3 分钟，扫完自动保存账号并校验）。已经有可用账号时不会打扰你，直接返回「无需登录」。mac / Linux 因为没有内置浏览器，会提示改用 -set-session。

几个实现上的点，用起来能感觉到：

• 无水印直链：从 SSE 里挑 image_raw / dwm3 模板地址（手工改后缀会 400，签名覆盖整个 path，只能用服务端给的）。

• 多图全量：服务端一次可能给 1~4 张，全部返回；结构化解析漏掉的图会从原文按图补回。

• 比例修正：服务端经常忽略请求比例，默认用虚化背景补齐到目标比例（偏差 3% 内不动）。

• 双通道降级：新端点 /chat/completion 失败自动降级到旧的 samantha 通道。

环境要求

• Windows 10 / 11：完整支持（GUI + 扫码登录），x64 / x86 / ARM64 都有预编译包。

• macOS / Linux：有预编译命令行版（MCP 功能完整），但没有 GUI、没有内置扫码登录，登录用 -set-session 手动导入（见安装 → 方式三）。想要 GUI 就在该平台上自己 wails build。

• Microsoft Edge WebView2 Runtime：仅 Windows 的扫码窗口需要；Win11 自带，Win10 若缺失程序会明确提示。

• 一个豆包账号（免费账号就能用 Seedream 5.0 Flash）。

下载

到 Releases 按你的平台选一个：

命令行版包含 -mcp（stdio）、-http、-set-session、-diagnose、-view 等全部命令，只是没有图形界面。 每个包都是「可执行文件 + README + LICENSE」，解压即用。mac/Linux 上首次运行可能需要 chmod +x doubao-image-mcp。

版本与更新检查

不需要任何服务器，直接用 GitHub 的版本管理当更新源。

• GUI 启动时会静默请求一次 GitHub 的最新 Release，发现新版本就在顶部弹一条提示（「去下载」直接开浏览器，「忽略此版本」记在本地，下次发版还会提醒）。

• 界面右上角还有**「检查更新」按钮**：手动查一次，检查期间按钮显示转圈 +「检查中」且不可重复点击，结果直接显示在按钮上（有新版本 / 已是最新 / 检查失败）。

• 命令行也能查：

  .\doubao-image-mcp.exe -version         # 当前版本
  .\doubao-image-mcp.exe -check-update    # 有没有新版本

原理就一句话：

GET https://api.github.com/repos/haikuotianko/doubao-image-mcp/releases/latest
→ 取 tag_name（如 v1.2.0）与二进制里编译进去的版本号比较

细节：

版本号比较规则：按 主.次.修订 逐段比数字（v1.10.0 > v1.9.0），同号时正式版高于预发布版（v1.4.0 > v1.4.0-beta）。

安装

方式一：下载 Release（推荐）

Windows：

1. 下载 …-windows-x64.zip（ARM 机器选 windows-arm64，32 位系统选 windows-x86）

2. 解压到任意目录（路径可以含中文和空格）

3. 双击 doubao-image-mcp.exe

程序是单文件，不需要安装。配置和账号写在 %APPDATA%\doubao-image-mcp，所以移动/改名 exe 不会丢账号。

macOS / Linux（命令行版）：

unzip doubao-image-mcp-v1.4.0-macos-arm64-cli.zip -d doubao-image-mcp
cd doubao-image-mcp && chmod +x doubao-image-mcp
./doubao-image-mcp -set-session "sessionid=…; ttwid=…"   # 整段 Cookie 直接粘，取法见下方
./doubao-image-mcp -mcp        # MCP 客户端拉起时用

首次从网上下载的二进制在 macOS 上可能被 Gatekeeper 拦，执行 xattr -d com.apple.quarantine ./doubao-image-mcp 即可。

方式二：从源码构建

需要 Go 1.22+、Node.js 18+、Wails CLI：

go install github.com/wailsapp/wails/v2/cmd/wails@latest
git clone https://github.com/haikuotianko/doubao-image-mcp.git
cd doubao-image-mcp
wails build          # 产出 build\bin\doubao-image-mcp.exe

只改后端时可以 go build ./... 快速验证编译。

方式三：macOS / Linux

MCP 本体（协议客户端、工具、账号池）是纯 Go，可以直接跑；缺的只是 Windows 那个内置扫码窗口，所以登录改成复制一次 Cookie。

# 需要 Go 1.22+（或者直接用 Release 里的 *-cli 包）
go build -o doubao-image-mcp .

# 1) 把浏览器里的 Cookie 整段粘进来（导入时会校验登录态、抓头像昵称）
./doubao-image-mcp -set-session "sessionid=xxxx; ttwid=yyyy; ..."

# 2) 交给 MCP 客户端
./doubao-image-mcp -mcp

怎么取 Cookie（三种都支持，任选一种）

① 复制整段 Cookie 请求头（最省事，不用自己找 sessionid）

1. 用浏览器打开 https://www.doubao.com 并登录

2. 按 F12 打开开发者工具，切到 Network / 网络 面板

3. 刷新页面（F5），在请求列表里点任意一条 doubao.com 的请求（比如 chat 或 completion）

4. 右侧找到 Request Headers / 请求标头 → 复制 cookie: 后面那一整行 （形如 sessionid=7f3c…; ttwid=1%7C…; s_v_web_id=verify_…; …）

5. 把整行粘到 -set-session 后面：

   ./doubao-image-mcp -set-session "sessionid=7f3c…; ttwid=1%7C…; s_v_web_id=verify_…"

   带不带 Cookie: 前缀都行，多几个无关 cookie 也没关系——程序只认它需要的那些。

② 直接右键「Copy as cURL」

在 Network 面板里右键任意请求 → Copy → Copy as cURL，把整段命令原样粘进来：

./doubao-image-mcp -set-session "curl 'https://www.doubao.com/chat/' -H 'cookie: sessionid=7f3c…; ttwid=1%7C…'"

程序会自动从 cURL 里把 cookie 头抠出来。

③ 只复制 sessionid（最少信息）

1. 开发者工具 → Application / 应用 → 左侧 Cookies → https://www.doubao.com

2. 找到名为 sessionid 的那一行，复制 Value（通常 32 位十六进制）

3. ./doubao-image-mcp -set-session "7f3c0d5e9a2b4c6d8e0f1a2b3c4d5e6f"

sessionid 是 HttpOnly，浏览器控制台里 document.cookie 看不到，必须在 Application → Cookies 或 Network → Request Headers 里复制。

想用 GUI 的话，mac/Linux 上编译出的界面里「扫码登录」会变成同一个导入框，粘贴方式和上面一样。

想要 GUI 的话：

# macOS：需要 Xcode 命令行工具（xcode-select --install）
# Linux：需要 GTK/WebKit2GTK 开发包，例如 Debian/Ubuntu:
#   sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
go install github.com/wailsapp/wails/v2/cmd/wails@latest
wails build

mac/Linux 上的 GUI 里，「扫码登录」按钮会换成手动导入 sessionid 的输入框，其余功能（账号池、排队、测试生图、大图查看、另存）都一样。

未验证：作者只有 Windows 机器，mac/Linux 只验证到「交叉编译通过」（GOOS=darwin / GOOS=linux go build . 都能出二进制）。真实运行、GUI 渲染、open/xdg-open 打开目录需要 macOS / Linux 用户帮忙验证；有问题请开 issue 附上 -diagnose 报告。

首次使用

1. 打开程序，点账号卡片右上角的 「扫码登录」（mac/Linux 是「导入 sessionid」）。

2. 弹出内置浏览器窗口，用豆包 App 扫码，窗口自动关闭。

3. 账号出现在列表里，带头像 + 昵称（登录成功后自动抓取）。

4. 在「设置」里选好输出目录（默认 图片\doubao-image-mcp）、默认模型/比例/风格。

加第二个账号：再点一次「扫码登录」。程序会先清空浏览器里的旧登录态、重新出二维码，并且把已有账号的 sessionid 排除在外，所以不会出现「一打开就显示已登录、第二个号扫不进去」的情况。

排序与默认账号：账号行可以拖动排序（顺序就是生图优先级）；「设置 → 默认账号」可以指定优先用哪个号，留空则用列表里第一个启用的账号。停用的账号不参与调度，也不会出现在两个账号下拉里。

接入 MCP 客户端

客户端配置里的路径不要手抄：GUI 的「MCP 服务」卡片会按当前机器的真实位置生成好可直接粘贴的 JSON，doubao-image-mcp.exe -diagnose 也会打印同一份。

方式一：stdio（推荐，客户端自己拉起进程）

{
  "mcpServers": {
    "doubao": {
      "command": "C:\\Users\\<你>\\Downloads\\doubao-image-mcp.exe",
      "args": ["-mcp"]
    }
  }
}

• Claude Desktop：改 %APPDATA%\Claude\claude_desktop_config.json，重启客户端。

• Cursor：Settings → MCP → Add new MCP server，选 command 类型，命令填 <路径>\doubao-image-mcp.exe -mcp。

• Cherry Studio / 其他：选「stdio」传输，命令和参数同上。

-mcp 模式下日志写到 %APPDATA%\doubao-image-mcp\mcp.log，stdout 只走 JSON-RPC，不会污染协议。

方式二：本地 HTTP（常驻，多客户端共用）

在 GUI 里点「启动 HTTP」，或命令行：

.\doubao-image-mcp.exe -http 127.0.0.1:8770   # 不带地址则用配置里的地址

客户端配置：

{
  "mcpServers": {
    "doubao": {
      "type": "http",
      "url": "http://127.0.0.1:8770/mcp"
    }
  }
}

⚠️ 这个 HTTP 接口没有鉴权，等于「谁连上谁就能花你的额度」。默认只绑 127.0.0.1，不要改成 0.0.0.0 或局域网地址。

怎么确认接上了

在客户端里问一句「用 doubao_ping 看看豆包登录态」，返回 账号 xxx 登录态正常 就通了。返回「还没有登录任何豆包账号」说明账号不在配置里，回 GUI 扫码即可。

工具参考

doubao_image —— 生成图片

返回里除图片外还会带 chat_id 与 chat_url：这次生成落在哪个对话，点链接就能在豆包网页版里看到（就是 https://www.doubao.com/chat/<id>）。

返回的文本是「共 N 张：」加每张一行路径；结构化输出：

{
  "prompt": "海边日落，电影感",
  "model": "Seedream 5.0 Flash",
  "ratio": "16:9",
  "channel": "ability",
  "notice": "",
  "images": [
    {
      "path": "C:\\Users\\me\\Pictures\\doubao-image-mcp\\doubao_20261106_153012_1.png",
      "url": "https://p3-flow-imagex-sign.byteimg.com/...",
      "width": 2048,
      "height": 2048,
      "format": "png"
    }
  ]
}

调用示例（任何 MCP 客户端替我发这个请求）：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "doubao_image",
    "arguments": {
      "prompt": "赛博朋克风格的重庆夜景，霓虹灯、雨夜、电影感",
      "ratio": "16:9",
      "model": "Seedream 5.0 Flash",
      "style": "image_gen_style_cyberpunk"
    }
  }
}

图生图就是多传参考图：

{
  "name": "doubao_image",
  "arguments": {
    "prompt": "把这张照片改成水彩画风格",
    "ref_images": ["C:\\Users\\me\\Pictures\\cat.jpg"],
    "ratio": "1:1"
  }
}

对 AI 说话就行，不用手写 JSON：

用 doubao_image 画一张「雪山日落，16:9，电影感」 用 doubao_image 把这四张图分别改成水彩风格：C:\pics\1.jpg …

doubao_models —— 查模型 / 风格 / 比例

无参数。返回：

{
  "models": [{"name": "Seedream 5.0 Flash", "sub": "专业快速（免费，推荐）", "needUpgrade": false}],
  "defaultModel": "Seedream 5.0 Flash",
  "styles": [{"key": "skill_image_styles_film", "name": "电影写真"}],
  "ratios": ["1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3", "auto"]
}

doubao_login —— 直接弹窗扫码

无参数。调用后会在你桌面上弹出豆包登录窗口，用 App 扫码即可；扫完自动保存账号、校验登录态、抓头像昵称。最长等 3 分钟，客户端取消请求时窗口会关闭。

{"name": "doubao_login", "arguments": {}}

返回：

{"ok": true, "account": "doubao-1106-165733", "nickname": "hai_lucky", "message": "登录成功，已保存账号 doubao-1106-165733，昵称 hai_lucky"}

• 已有可用账号时不弹窗，直接返回「已经有可用账号 xxx，无需登录」。

• 非 Windows 平台返回提示：用 -set-session 手动导入。

• 也可以直接对 AI 说：「先 doubao_login 登录一下，再画一张…」

doubao_ping —— 检查登录态

无参数。返回 {ok, account, message}。风控（710022002 / 710022004）和登录失效都在 message 里说明。

doubao_verify —— 过滑块验证

无参数。生图报 710022004（人机验证）时调用它：会在你桌面上打开一个豆包窗口（已带上当前账号的登录态），你随便发一条消息触发滑块、拖过去、把窗口关掉，再重新调 doubao_image 即可。

有图形界面的版本还有按钮入口：设置里的 「去验证（滑块）」。

验证状态有有效期，且和 IP 绑定；验证期间以及风控冷却期不要开豆包网页版——网页版会持续请求同样的接口，相当于一直在续命风控状态，冷却时间会被拉长。

doubao_accounts —— 账号池

返回包含 active（默认账号）、waiting（排队请求数）和账号列表：

{
  "active": "doubao-1106-152143",
  "waiting": 0,
  "accounts": [
    {"name": "doubao-1106-152143", "nickname": "hai_lucky", "enabled": true, "busy": false, "active": true}
  ]
}

多账号与自动排队

生图请求（MCP 与 GUI 测试共用同一个池）按下面的规则走：

1. 默认账号优先，其余按列表顺序，挑一个空闲的已启用账号；

2. 每个账号同一时刻只跑一个任务（豆包对并发不友好，容易踩风控）；

3. 全忙就排队等待，不会直接失败；排队数显示在顶部徽标和 doubao_accounts 的 waiting 里；

4. 一个可调度账号都没有时，明确报「没有启用中的账号」。

排队只在同一个进程内生效。stdio 模式下每个 MCP 客户端会拉起自己的进程，多个客户端之间不共享队列；要严格串行就用 HTTP 模式（一个进程服务所有客户端）。

会话复用与上下文隔离

默认所有生成都放进同一个对话（可在「设置 → 复用对话」关掉）。这样豆包网页版里不会因为每次生图多出一堆会话，也方便你回头在网页里接着聊。

规则：

1. 第一次生成时把服务端返回的会话 id（conversation_id）记到该账号名下；

2. 之后的生成带上它，追加到同一个对话里；

3. 找不到记录、或在这个对话里生成失败 → 自动新建一个对话重发一次，并记下新 id；

4. 每个账号各记各的，换账号就是另一个对话。

因为复用对话意味着新提示词会看到前面的图，所以多了「上下文隔离」三档（设置里可选，也可用 context_mode 参数临时覆盖）：

想手动指定对话，把网页地址直接丢进去就行——chat_id 既收纯数字 id，也收 https://www.doubao.com/chat/<id> 这样的链接（程序会把 id 取出来）。返回里的 chat_url 就是这次落到的对话地址。

旧通道（samantha 兜底、图生图）不返回会话 id，这种情况程序会清掉本地记录，下次重新建对话，避免往一个已经不对的对话里发。

数据位置

排障

扫码窗口白屏 / 打不开

登录窗口是原生 WebView2，出问题基本是运行时、代理或网络三类。程序会把这些情况写进窗口和日志：

1. 加载失败时窗口里直接显示原因（连不上服务器 / DNS 失败 / 代理要认证 / 渲染进程崩溃），不再是白屏。

2. 页面「加载成功但整页空白」（老 WebView2 运行时跑不动豆包前端）会被探针识别并提示。

3. 跑一次自检，把报告发回来：

   .\doubao-image-mcp.exe -diagnose

   报告落在 %APPDATA%\doubao-image-mcp\diag-<时间>.txt，含 Windows 版本、WebView2 运行时版本、配置目录可写性、代理设置、DNS/TCP/HTTPS 连通性，以及按当前机器路径生成好的 stdio 配置。

其它命令行开关

.\doubao-image-mcp.exe -login                  # 只开登录窗口（日志写 app.log）
.\doubao-image-mcp.exe -login -login-url about:blank   # 换个地址，验证窗口本身是否正常
.\doubao-image-mcp.exe -view                   # 用默认账号的会话开浏览器窗口
.\doubao-image-mcp.exe -diagnose               # 环境自检
.\doubao-image-mcp.exe -version                # 打印当前版本
.\doubao-image-mcp.exe -check-update           # 查 GitHub 上有没有新版本

生成失败

已知限制

• 走的是网页版接口，属于逆向实现，没有官方保证；豆包改接口就可能失效。

• 免费账号有额度限制。

• 图生图（ref_images）走旧的 samantha 通道，比文生图脆弱。

• 服务端有时忽略请求的比例；默认的 fit_ratio 会用虚化背景补齐，关掉就保留原图。

• 仅 Windows（见下）。

跨平台说明

MCP 主体是纯 Go（internal/doubao 协议客户端、internal/mcpserver 工具定义、internal/accountpool 调度、internal/config 持久化），因此 7 个平台的包都是同一份代码编出来的：

一键打完所有包：

powershell -File scripts\build-release.ps1 -Version v1.4.0

发版后官网的下载列表要跟着更新（官网读的是仓库里的静态 docs/latest.json，不实时查 GitHub API，避免 60 次/小时的限流）：

powershell -File scripts\update-latest.ps1            # 取最新 Release
powershell -File scripts\update-latest.ps1 -Tag v1.4.0 # 或指定版本
git add docs/latest.json && git commit -m "docs: 更新 latest.json" && git push

为什么 mac/Linux 没有 GUI 包：Wails 的图形界面要 cgo（mac 用 WKWebView，Linux 用 WebKitGTK），而 cgo 无法在 Windows 上交叉编译，wails build -platform darwin/arm64 会直接告警 Crosscompiling to Mac not currently supported。所以这两个平台发的是纯 Go 的命令行版——MCP 功能完整，只是没有窗口。想要 GUI 就在对应平台上跑一次 wails build。

平台差异被收敛到三处，都用构建标签分开了：

现状：

• macOS / Linux 上 MCP 功能齐全（生成、多图、账号池、排队、-set-session 导入登录态）。

• 没有内置扫码窗口——sessionid 是 HttpOnly，只能从浏览器里手动取；这属于「用起来麻烦一点」，不是「不能用」。

• GUI 也能编译（wails build），但作者只有 Windows 环境，GUI 在 mac/Linux 上的实际渲染与交互未经我验证。如果你跑了，欢迎把结果/截图开 issue 反馈。

想补上原生扫码登录的话，路径是：mac 用 WKWebView + WKHTTPCookieStore 取 cookie，Linux 用 WebKitGTK 的 CookieManager；接口已经按 Options/Window/WaitLogin 抽好，加一个 window_darwin.go 即可，不需要动上层。

开发

wails build        # 产出 build\bin\doubao-image-mcp.exe
wails dev          # 热重载
go build ./...     # 只编译后端
go test ./internal/...   # 账号池 / 配置的单元测试

交叉编译自检（不需要 Mac 也能确认平台代码没断）：

GOOS=darwin  GOARCH=arm64 go build -o /tmp/mac .
GOOS=linux   GOARCH=amd64 go build -o /tmp/linux .

代码结构：

main.go                  启动模式（GUI / -mcp / -http / -diagnose / -login / -view）
diagnose.go              环境自检报告
app.go                   Wails 绑定：设置、账号、扫码登录、测试生图、图片另存、落盘日志
internal/config          配置与账号持久化（账号池顺序、启用状态、昵称头像）
internal/accountpool     账号调度：按优先级取空闲账号，全忙排队
internal/doubao          豆包协议客户端（SSE 解析、多图归并、图生图、上传、比例修正、资料抓取）
internal/loginwin        原生 Win32 + WebView2 登录窗口（取 HttpOnly cookie、错误页、空白探针）
internal/mcpserver       MCP 工具定义（stdio / streamable HTTP）
internal/update          GitHub Releases 版本检查与版本号比较（不需要自建服务器）
internal/version         构建时用 -ldflags 注入的版本号
frontend/                Vanilla JS + vite

调试小技巧：设 DOUBAO_MCP_DUMP_SSE=<文件路径> 会把这次生成的原始 SSE 写到该文件，方便服务端改结构时对齐字段。

许可证与免责

MIT。软件按「现状」提供，不附带任何明示或暗示的担保。

⚠️ 非官方项目：这里调用的是豆包网页版接口，属于逆向实现，随时可能因服务端调整而失效。仅供个人学习与自用，请遵守豆包用户协议；请不要用它批量刷额度、对外提供服务或分发他人账号。