OpenCode 对接 Flux MCP

📘 Overview：OpenCode MCP Overview →

Black Forest Labs 出品的 Flux 系列是当前写实风格表现最强、图片编辑能力（Kontext）最方便的开源图像模型之一。在 OpenCode 里接上 Flux MCP Server 之后，可以直接让 AI 根据当前对话上下文生成或编辑图片，适合做商用素材和高保真插画。

Flux MCP 适合做产品 hero 图、写实人像、商业广告素材，以及通过 Kontext 模型做“按文字描述编辑现有图片”——比如换背景、换风格、改字。

获取 API Token

使用 Flux MCP Server 之前，需要先准备一个 Ace Data Cloud API Token。OpenCode 和 Claude Code 共用一套 Token，获取流程一样：

打开 Ace Data Cloud 控制台 - 应用列表，获取您的 API Token，留作备用。
如果你尚未登录或注册，会自动跳转到登录页面；登录注册之后会自动返回当前页面。
首次申请时会有免费额度赠送，可以先免费体验 Flux MCP 服务。

一个 Token 可以使用 AceData Cloud 提供的全部 11 个 MCP Server，无需为 Flux 单独申请。文档和截图里建议只展示脱敏形式，例如 3b78cc40dd3b43db806a4300....，不要把完整 Token 贴到公开仓库、Issue、截图或聊天记录里。

想用 Claude Desktop / Claude.ai 网页版直接 OAuth 一键授权？请看 Flux MCP 的 Claude.ai / Desktop 教程。

配置 OpenCode

OpenCode 用一份 opencode.json 描述所有 MCP Server，文件可以放在两处，按下面”作用范围”选一种即可。两种位置的字段结构完全相同，区别只是优先级。

强烈推荐先把 Token 写到环境变量里：

1	export ACEDATACLOUD_API_KEY="替换为你的真实 Token"

然后在 opencode.json 里用 {env:ACEDATACLOUD_API_KEY} 占位符引用，避免真实 Token 写进文件。

全局：所有项目共用

文件位置：~/.config/opencode/opencode.json，适合”我自己的机器，一次配好，所有项目都能用”。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flux": {
      "type": "remote",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

⚠️ "oauth": false 不可省略。AceData 的 MCP Server 使用 Bearer Token 鉴权，不走 OAuth 流程；OpenCode 默认会把 401 当成 OAuth 挑战自动重定向，导致 opencode mcp list 出现 SSE error: Non-200 status code (401)。显式声明 "oauth": false 让 OpenCode 直接以 Authorization: Bearer ... 调用，opencode mcp debug flux 也会回显 OAuth explicitly disabled，代表生效。

项目级：仅当前项目生效

文件位置：当前项目根目录下的 opencode.json，会覆盖全局配置。适合团队共享、单仓库定制，或者只在某个项目里临时启用某个 MCP。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flux": {
      "type": "remote",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

如果项目级 opencode.json 会被提交到 Git，请确保用 {env:ACEDATACLOUD_API_KEY} 占位符而不是真实 Token，避免泄露。

💡 如果 Shell 里的 .env 没有显式 export，需要用 set -a && source .env && set +a 才能把变量传给 OpenCode 进程，否则 opencode debug config 会显示 "Authorization": "Bearer "（占位符没解析）。

真实运行结果

下面是在 OpenCode 1.15.13 里用隔离临时目录实际执行后的脱敏输出。命令使用真实 AceData Cloud Token，输出中的 Token 已替换成 357265014ad145fc8ab2....，临时配置已删除。

$ opencode --version
1.15.13

$ opencode mcp list

┌  MCP Servers
│
●  ✓ flux connected
│      https://flux.mcp.acedata.cloud/mcp
│
└  1 server(s)

看到 ✓ flux connected 就说明 Flux MCP 已经接入成功。如果显示 ✗ 或者 unauthorized，请检查 ACEDATACLOUD_API_KEY 是否设置、Token 是否复制完整、Authorization 前缀是否为 Bearer（注意大小写和空格）。

如需调试某一台 MCP 的连接细节：

1	opencode mcp debug flux

实际握手成功后，OpenCode 的 INFO 日志会输出 service=mcp key=flux transport=StreamableHTTP connected 和 service=mcp key=flux toolCount=6 两行（实测 6 个工具），代表 Flux MCP 已经准备好被模型调用。

🤖 选模型的实测建议：在 OpenCode 里要真正让模型主动调用 Flux MCP，请优先使用 OpenAI 系列模型（如 acedatacloud/gpt-5-mini、acedatacloud/gpt-5）。AceData 上 Claude 系列模型通过 OpenAI 兼容接口暴露时，工具调用经常返回 Improperly formed request（实测：acedatacloud/claude-haiku-4-5-20251001、acedatacloud/claude-sonnet-4-6 在挂载多个 MCP 时均报这个错）。只做对话不调用工具时，Claude 模型可以正常使用。

典型场景

配置完成后，直接在 OpenCode 会话里用自然语言即可调用，无需先切到 /mcp：

快速出图

1	用 Flux 生成一张赛博朋克风格的城市夜景，霓虹灯、雨夜、湿润街道

Kontext 编辑现有图

1	把这张图（链接 xxx）改成水彩画风格

生成产品 hero 图

1	生成一张 1024x1024 的产品 hero 图：黑色金属质感的耳机悬浮在白色背景

工具列表

下表列出主要工具（Flux MCP Server 实测共暴露 6 个工具，可通过 curl -X POST https://flux.mcp.acedata.cloud/mcp -H 'Authorization: Bearer <token>' -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' 获取完整清单）：

工具	说明
flux_generate_image	文生图（Flux pro / dev / ultra）
flux_edit_image	对已有图按提示词编辑（Flux Kontext pro / max）

静觅崔庆才的个人站点 - Python爬虫教程