Listenseu Image MCP

让用户在自己的 Codex 中，通过本地 MCP 调用 https://api.listenseu.top 的图像接口。

这个项目的默认凭据流程是：

用户用个人 API Key 登录 Codex
        ↓
Codex 的 active model provider = https://api.listenseu.top/v1
        ↓
MCP 启动器验证 provider，然后读取本机 Codex 登录凭据
        ↓
调用 api.listenseu.top/v1/images/generations 或 /v1/images/edits

安装器不会再次询问 API Key，也不会把 Key 写入 GitHub、MCP 配置或仓库文件。启动器只在 provider 地址匹配时复用凭据；如果用户当前登录的是其他 provider，MCP 会拒绝启动。

功能

工具	用途
image_generate	文生图
image_edit	单张本地图片编辑，可选 PNG mask
image_batch_edit	对多张图片逐张执行同一编辑指令
image_multi_reference	融合 2-10 张参考图生成一张图
server_info	查看中转站、模型、凭据状态和安全边界

当前固定使用 gpt-image-2 和 https://api.listenseu.top。输出默认保存到用户的 Pictures/listenseu-out 目录。

前置条件

• 已安装 Codex CLI/桌面版，并能运行 codex 命令。
• Python 3.11 或更高版本。
• 用户已经在 Codex 中配置 https://api.listenseu.top/v1 为当前模型提供商。
• 用户已经使用自己的 API Key 登录 Codex。Key 必须存在于 Codex 的本机登录凭据中；本项目不会让用户在安装器里再次输入。

如果还没有配置 provider，可以在 Codex 配置中使用类似结构（名称可自定义）：

model_provider = "ListenSEU"

[model_providers.ListenSEU]
name = "ListenSEU"
base_url = "https://api.listenseu.top/v1"
wire_api = "responses"
requires_openai_auth = true

保存后，用 Codex 自己的登录流程完成个人 API Key 登录。不要把真实 Key 粘贴到 README、命令行参数或 GitHub Issues。

安装

在用户本机执行：

git clone https://github.com/Listen-Sun/listenseu-image-mcp.git
cd listenseu-image-mcp
python install.py

安装器会：

1. 检查 Codex 当前 provider 是否为 https://api.listenseu.top/v1。
2. 检查 Codex 本机是否已有个人 API 登录凭据（只检查存在性，不打印值）。
3. 创建仓库内虚拟环境并安装依赖。
4. 做一次不联网的 MCP initialize + tools/list 握手。
5. 用 codex mcp add 注册 listenseu-image。

安装完成后重启 Codex，然后让它调用：

调用 listenseu-image 的 server_info，检查 api_key_configured。

正常结果应包含：

{
  "base_url": "https://api.listenseu.top",
  "api_key_configured": true,
  "credential_is_returned": false
}

如果已有同名 MCP，需要明确允许替换：

python install.py --yes

只检查登录状态，不安装：

python install.py --check

只安装依赖并做握手、不改 Codex 配置：

python install.py --skip-register

卸载 MCP 配置（不删除仓库和虚拟环境）：

python install.py --uninstall

使用方式

内置 $imagegen 是 Codex 自带工具，它不会因为安装了本项目就自动改用第三方中转站。要确保请求走你的中转站，请在任务中明确要求使用 listenseu-image，例如：

使用 listenseu-image 的 image_generate，生成一张 1024x1024 的……

编辑本地图片时：

使用 listenseu-image 的 image_edit，读取 C:\\path\\input.png，只改变背景……

输入图片必须是本机可读的 PNG、JPEG 或 WebP。MCP 会先验证文件格式和大小，再上传到 /v1/images/edits。

尺寸与输出

• 宽高必须是 16 的倍数。
• 边长范围为 256-3840。
• 总像素范围为 655,360-8,294,400。
• 长宽比不能超过 3:1。
• 2K/4K 请求只允许 n=1，避免意外放大费用。
• 生成结果会先验证图片格式，再以原子方式保存，避免留下半个文件。
• save_dir 必须位于 LISTENSEU_SAVE_DIR_ROOT 之下；默认根目录是 ~/Pictures/listenseu-out。

安全设计

• API Base URL 写死为 https://api.listenseu.top，工具参数不能改写到任意站点。
• 启动器先比对 Codex 当前 active provider，再读取 ~/.codex/auth.json 中的 OPENAI_API_KEY。
• Key 只保存在 MCP 进程内存中，不写入 MCP 环境变量，也不会被子进程继承。
• MCP 工具没有 api_key 参数，模型不能通过工具参数转发密钥。
• server_info 只返回布尔状态和来源标签，不返回 Key。
• 上游返回 URL 时，只接受 HTTPS，并拒绝解析到本机、内网或保留地址。
• 任何日志、截图、Issue 或测试输出都不得包含真实 Key。

常见问题

api_key_configured 是 false

确认 Codex 当前 provider 的 base_url 精确为 https://api.listenseu.top/v1，并确认 Codex 登录凭据中有 OPENAI_API_KEY。改完后完全重启 Codex，让 MCP 子进程重新读取凭据。

安装器提示 provider 不匹配

这是故意的安全阻断。它不会把当前其他 provider 的 Key 发送到你的中转站。先切换到 ListenSEU provider，再运行安装器。

请求仍然走 OpenAI 官方

不要只说“生成一张图”，而要明确要求调用 listenseu-image 的工具。内置 $imagegen 与这个 MCP 是两个独立的工具入口。

编辑请求返回 HTTP 400

请先用 image_generate 验证登录和生成线路，再检查参考图格式、尺寸和大小。当前中转站的具体模型/编辑能力以 server_info 和接口返回为准。

官方参考

• Codex MCP 配置（OpenAI Docs）
• Codex 配置文件

许可证

本项目使用 MIT License，见 LICENSE。