pixelgate

pixelgate is a stdio MCP server that gives Claude Code two image tools, generate_image and edit_image. Requests go only to a CLIProxyAPI gateway on the loopback interface, which forwards them to GPT Image models using your own ChatGPT subscription; pixelgate itself holds no upstream credentials. It is an unofficial personal project and is not affiliated with or endorsed by OpenAI or Anthropic. Routing a subscription through a gateway may conflict with the providers' terms of service, so use it at your own risk. The rest of this document is in Chinese.

1. 这是什么

pixelgate 是一个 stdio 传输的 MCP 服务，向 Claude Code 提供生成图片与编辑图片两个工具。它把请求发给本机回环地址上的 CLIProxyAPI 网关，由网关用 ChatGPT 订阅的凭据转发到 GPT Image 后端。pixelgate 不持有任何上游凭据，也不调用网关的管理接口；每次调用生成一张图，产物连同回执写进调用方指定的目录。

支持的客户端是 Claude Code，包括经 claudex 启动的 Claude Code 会话（claudex 把 Claude Code 的模型请求转到同一个本机网关）。Codex 自带原生的图像生成能力，不需要也不支持接入本服务。

Related MCP server: imaginate-mcp

2. 前置条件

• uv，以及 uv 托管的 Python 3.14（uv python install --no-bin 3.14）。

• 一个在本机运行的 CLIProxyAPI 网关：已用 ChatGPT 订阅登录，监听 127.0.0.1 上的某个端口，并配置了一个供客户端使用的 key。本包要求这个 key 是 64 位小写十六进制串，可以用 openssl rand -hex 32 生成。

• 一个读取这个 key 的可执行文件（下称 helper）：无参数运行，stdout 恰好输出一行 key。最简单的写法是把 key 存进一个权限 0600 的文件，helper 只 cat 它：

  #!/bin/sh
  exec cat "$HOME/.config/pixelgate/client.key"

3. 安装

uv tool install --python 3.14 "pixelgate @ git+https://github.com/0-Br/pixelgate@v0.1.0"

安装后命令 pixelgate 在 ~/.local/bin 下。运行依赖在 pyproject.toml 里钉死版本，因为 uv tool install 不读 uv.lock，钉死才能与开发环境一致。升级时换 tag 重新执行同一条命令并加 --reinstall。

4. 配置

mkdir -m 700 ~/.config/pixelgate
cp config.example.json ~/.config/pixelgate/config.json   # 在仓库根目录执行
chmod 600 ~/.config/pixelgate/config.json
pixelgate check-config --config ~/.config/pixelgate/config.json

check-config 对合法配置打印 ok，否则退出码 2，并在 stderr 给出错误类别。配置文件有四个字段，出现别的字段即拒绝：

model_routes 的值必须是只归属订阅凭据的请求名。同一个模型名可能同时登记在网关里别的 provider（例如按量计费的 API key）下面，而网关不提供按 provider 选路，所以名字相同不等于走同一条路由。填写前经网关管理接口 GET /v0/management/auth-files 与 /v0/management/auth-files/models?name=<文件名> 核对：两个名字只出现在订阅登录的那份凭据上才能直接填；否则先在网关里给订阅凭据配一个唯一的别名（oauth-model-alias），再把别名填进来。核对时只看文件名、provider、账户类型与模型名，凭据文件的其余字段可能含真实的 key，不要打印。

配置文件缺失、JSON 非法、版本不符、有未知字段、helper 不存在或不可执行时，服务一启动就以退出码 2 结束。网关没有运行时，工具调用返回错误类别 gateway_unreachable；pixelgate 不负责拉起网关。

5. 在 Claude Code 中注册

claude mcp add --scope user pixelgate -- ~/.local/bin/pixelgate --config ~/.config/pixelgate/config.json

注册后工具名是 mcp__pixelgate__generate_image 与 mcp__pixelgate__edit_image。两个工具在工具清单里都带 _meta["anthropic/requiresUserInteraction"]=true，Claude Code 每次调用前都会请用户批准。

6. 工具

图片引用的形态是 {"path": "<绝对路径>", "sha256": "<64 位小写十六进制>"}。发出请求前逐张核对：文件存在；不超过 32 MiB；哈希与声明一致；Pillow 能识别（png、jpeg、webp）并完整解码；宽或高不超过 8192，总像素不超过 16,777,216。发送的是读取时形成的内存快照。mask 必须与 parent 格式相同、尺寸相同，并且带 alpha 通道。

每次请求固定发送 n=1、output_format="png"、stream=False，客户端不重试。HTTP 超时为 600 秒，按单次读写操作计，所以上游持续慢速回传时，整次调用可能超过 600 秒。同一个服务进程里已有调用在跑时，第二个调用立即返回 busy，不排队；锁只在进程内生效，同时开着的两个 Claude Code 会话各连一个服务进程，彼此不互斥。

本版没有取消通道：客户端取消一次调用时，服务仍等工作线程跑完，那一次的产物与终态回执照常写盘（成功即 completed），只是客户端拿不到返回。要知道结果，读 output_dir 下最新产物目录里的 receipt.json。

成功时，structuredContent 是回执摘要，content 是一段文本（图片路径、预览路径、尺寸、格式、state）加一个 JPEG 预览图像块。预览质量 85，最长边从 768 像素起，按 100 KB 的 base64 预算依次降到 512、384；仍超预算就省略图像块，并在 warnings 里记 preview_omitted。失败时 isError=true，文本只含错误类别与不含敏感信息的字段，structuredContent 同样是回执摘要。

7. 产物

每次调用在 output_dir 下排他创建目录 <UTC 时间戳>-<uuid4 前 8 位>/（目录权限 0700，文件 0600），内容如下：

输入预检失败时不创建目录；任何目标文件已经存在即报 artifact_collision，不覆盖。

回执字段（缺失的值写 null，不拿请求值冒充返回值）：

state 的含义：started 在请求发出前写入；completed 只在图片解码成功、全部文件写盘之后写入；请求发出后连接中断、超时或写盘前中断，写 unknown；本地预检失败、建连失败（请求没有发出）与上游返回明确错误，写 failed。持久回执停在 started 的，是进程被杀或机器重启留下的，读取者应理解为「上游结果未知」；本版不做恢复扫描。MCP 返回的摘要包含 request_id、operation、state、requested_model、actual_model、output、preview、size_mismatch、usage、error、warnings、artifact_dir。

output_dir 由调用方给出，本包不设默认值。建议固定用一个用户级的生成库，例如 ~/.local/share/pixelgate/，放在任何 git 仓库之外：每个时间戳目录是一次调用的过程产物，用于溯源与核对额度，数量会随着试构图和改稿不断增长。选中的成品由使用者复制进项目自己的资产目录，随项目做版本管理。清理时按时间戳目录整个删除，删之前看一眼 receipt.json，确认没有别处还在引用它；本包不做自动清理。

8. 错误类别

下表是完整枚举：

9. 安全边界

• 构造客户端期间，临时摘掉 OPENAI_BASE_URL、OPENAI_API_KEY、OPENAI_CUSTOM_HEADERS 等 OPENAI_* 变量与各个代理环境变量，构造完成后原样放回；HTTP 客户端不读环境里的代理设置，也不读 .env。

• 传输层只放行 http://127.0.0.1:<配置端口> 下的 /v1/images/generations 与 /v1/images/edits，不跟随重定向。

• client key 只在进程内经 helper 取得，不进参数、日志、回执与返回。

• stdout 上只有 MCP 协议帧；诊断信息写 stderr，而且不含 prompt、图片内容、上游原文与凭据。

10. 开发

uv sync --locked --group dev --python 3.14
uv run --locked pytest
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked basedpyright

测试全部离线：tests/conftest.py 提供合成图片、假 HOME 下的合成 key、回环上的假网关、代理陷阱与诱饵网关，不访问真实网关。类型检查相对仓库里的基线 .basedpyright/baseline.json 不新增 error。

11. 许可证

MIT，见 LICENSE。