my-image-mcp

一个独立的 MCP 图片服务：使用你自己的 OpenAI 兼容 Images API，在支持 MCP 的 AI 客户端、Dify 和 n8n 中生成、编辑、组合图片和使用 mask。

• 默认模型：gpt-image-2

• 接口：自定义 Base URL 和 API Key

• 传输：本地 stdio、Streamable HTTP /mcp、兼容 SSE /sse

• 系统：macOS、Windows、Linux

• 结果：图片块、结构化字段、文本降级、原图路径或限时链接

• 安全：Key 不进入工具参数或聊天记录；本地设置页仅监听 127.0.0.1

English README

最简单的用法

需要 Node.js 20 或更高版本。这个仓库目前没有发布到 npm，所以从源码安装：

git clone https://gitee.com/chenyifan888/my-image-mcp.git
cd my-image-mcp
npm ci
npm run build

然后在 AI 客户端中添加一个本地 MCP 服务：

{
  "mcpServers": {
    "my-image": {
      "command": "node",
      "args": ["/这里换成绝对路径/my-image-mcp/dist/cli.js"]
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "my-image": {
      "command": "node",
      "args": ["C:\\Users\\你的名字\\my-image-mcp\\dist\\cli.js"]
    }
  }
}

重启客户端后直接说“生成一张真实的小猫图片，轮廓光”。如果还没有 Key，工具会自动返回一个一次性本地设置网址。打开网页，只填写服务商给你的 Base URL 和 API Key；不用创建 .env，也不要把 Key 发到聊天里。

配置保存在当前系统用户的应用配置目录。macOS、Windows 和 Linux 路径不同，程序会自动选择，并在 Unix 系统尽量使用 0600 权限。

更多客户端模板见 examples/clients。

Related MCP server: AI Image MCP Server

工具

尺寸省略或填 auto 时，服务会根据描述中的用途、横竖构图、比例和清晰度选择尺寸。明确写出的尺寸或比例优先。例如：

{
  "prompt": "真实建筑室内，横版网站首屏，电影感自然光",
  "delivery": "auto"
}

编辑时，images 是 1 到 16 个字符串。可使用服务所在机器允许目录内的本地路径、公共 HTTPS URL、Data URL 或纯 Base64：

{
  "prompt": "保留人物和构图，把背景改成雨夜霓虹街道",
  "images": ["/绝对路径/input.png"],
  "mask": "/绝对路径/mask.png",
  "delivery": "both"
}

远程 MCP 服务器看不到你电脑上的本地路径；远程工作流请使用公共 HTTPS URL 或 Base64。

图片交付

delivery 支持：

原图会写入用户数据目录，预览位于 .previews 子目录。远程 HTTP 返回 HMAC 签名的短期下载链接；链接不包含 Key、prompt 或本地路径。

HTTP 服务

本机调试：

node dist/cli.js --transport http --host 127.0.0.1 --port 3000

端点：

• Streamable HTTP：http://127.0.0.1:3000/mcp

• 旧 SSE：http://127.0.0.1:3000/sse

• 健康检查：http://127.0.0.1:3000/health

监听 0.0.0.0 或非回环地址时，程序拒绝无认证启动，并要求 MY_IMAGE_MCP_TOKEN、MY_IMAGE_ALLOWED_HOSTS 和用于原图链接的 MY_IMAGE_PUBLIC_BASE_URL。MCP 入站 token 和图片 API Key 是两个不同的凭据。

Docker 服务器部署需要环境变量，见 .env.example 和 compose.yaml：

docker compose up --build -d

生产公网部署还应在反向代理上启用 HTTPS。完整 OAuth 可由网关或授权服务提供，本项目不自建 OAuth 身份系统。 一次性设置网页只用于本地 stdio；远程 HTTP 未配置时会要求服务器管理员设置环境变量，不会返回一个对工作流用户不可访问的服务器 localhost 地址。

部署到公网服务器

下面以一台全新的 Ubuntu/Debian 服务器、域名 image.example.com 和 Nginx 为例。完成后，Dify、n8n 等远程工作流使用的 MCP 地址是 https://image.example.com/mcp。

1. 准备服务器和域名

• 准备一台有公网 IP 的 Linux 服务器，建议至少 1 核 CPU、1 GB 内存和 10 GB 磁盘。

• 在域名服务商处添加一条 A 记录，把 image.example.com 指向服务器公网 IPv4；使用 IPv6 时再添加 AAAA 记录。

• 在云服务器安全组中只放行 SSH 22、HTTP 80 和 HTTPS 443。不要向公网开放 3000。

• 等待 DNS 生效，可以在自己电脑上执行 nslookup image.example.com，确认结果是服务器 IP。

2. 安装 Docker

SSH 登录服务器后执行：

sudo apt update
sudo apt install -y git curl ca-certificates nano openssl
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
rm get-docker.sh
sudo usermod -aG docker "$USER"
newgrp docker
docker compose version

最后一条命令能显示 Compose 版本即可。生产环境也可以按 Docker 官方文档 使用软件源安装。

3. 下载项目并填写配置

git clone https://gitee.com/chenyifan888/my-image-mcp.git
cd my-image-mcp
cp .env.example .env
openssl rand -hex 32
nano .env

openssl 最后一条输出是你自己生成的 MCP Token，把它粘贴到 MY_IMAGE_MCP_TOKEN。.env 至少修改下面这些值：

# 生图服务商提供；程序会在这个地址后调用 /images/generations 和 /images/edits
MY_IMAGE_BASE_URL=https://api.example.com/v1
MY_IMAGE_API_KEY=替换成生图服务商的APIKey
MY_IMAGE_MODEL=gpt-image-2

# 这是你自己生成的 MCP 入站密码，不是上面的生图 API Key
MY_IMAGE_MCP_TOKEN=替换成openssl生成的长随机字符串

# 这里只写域名，不要带 https://、端口或路径
MY_IMAGE_ALLOWED_HOSTS=image.example.com

# 这里必须是外部用户实际访问的完整 HTTPS 地址，不要以 /mcp 结尾
MY_IMAGE_PUBLIC_BASE_URL=https://image.example.com

# Docker 只把端口开放给同一台服务器上的 Nginx
MY_IMAGE_MCP_BIND=127.0.0.1
MY_IMAGE_MCP_PORT=3000
MY_IMAGE_TIMEOUT_MS=300000

MY_IMAGE_MCP_BIND 是 Docker 在宿主机上的监听地址。按上面的值填写时，公网无法绕过 Nginx 直接访问 3000。只有明确需要让局域网设备直连时，才把它改为 0.0.0.0，同时配置防火墙。

如果只由 Dify/n8n 服务端调用，MY_IMAGE_ALLOWED_ORIGINS 可以留空。保存后限制配置文件权限并启动：

chmod 600 .env
docker compose config --quiet
docker compose up --build -d
docker compose ps
docker compose logs --tail=100

docker compose config --quiet 只检查配置，不会把展开后的 API Key 和 Token 打印到终端。不要把 --quiet 去掉后再复制或分享输出。

看到容器为 running 或 healthy 后，在服务器上检查内部健康状态。Host 必须与 MY_IMAGE_ALLOWED_HOSTS 一致：

curl -H 'Host: image.example.com' http://127.0.0.1:3000/health

正常结果：

{"status":"ok","service":"my-image-mcp"}

4. 配置 Nginx 和 HTTPS

安装 Nginx 与 Certbot：

sudo apt install -y nginx certbot python3-certbot-nginx
sudo nano /etc/nginx/sites-available/my-image-mcp

写入以下配置，并把两处域名换成自己的域名：

server {
    listen 80;
    listen [::]:80;
    server_name image.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

启用站点并申请免费 HTTPS 证书：

sudo ln -s /etc/nginx/sites-available/my-image-mcp /etc/nginx/sites-enabled/my-image-mcp
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d image.example.com

Certbot 会询问邮箱并要求同意条款，完成后会自动修改 Nginx 配置并设置续期。现在从自己电脑测试：

curl https://image.example.com/health
curl -i https://image.example.com/mcp

第一条应返回健康状态；第二条没有携带 Token，应返回 401 Unauthorized，这说明 MCP 鉴权已生效。不要为了让第二条返回成功而关闭鉴权。

还可以执行一次不会产生图片费用的 MCP 握手。输入 Token 时终端不会显示明文：

read -rsp 'MCP Token: ' MCP_TOKEN; echo
curl -i https://image.example.com/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-check","version":"1.0.0"}}}'
unset MCP_TOKEN

正常响应的 HTTP 状态是 200，JSON 中应出现 serverInfo.name 为 my-image-mcp。

5. 连接 Dify 或 n8n

远程平台只需要下面两个值，不需要知道生图 API Key：

MCP URL: https://image.example.com/mcp
Authorization: Bearer <MY_IMAGE_MCP_TOKEN>

Dify 的具体参数见下一节；n8n 使用相同 URL 和 Bearer Token。首次连接后应能看到 generate_image、edit_image、image_config_status 和 setup_image_api 四个工具。远程部署不使用 setup_image_api，Base URL 和 API Key 由服务器管理员在 .env 中维护。

更新和排错

更新服务：

cd my-image-mcp
git pull --ff-only
docker compose up --build -d
docker compose logs --tail=100

不要执行 docker compose down -v，其中 -v 会删除保存生成图片和签名密钥的持久卷。

查看实时日志使用 docker compose logs -f，按 Ctrl+C 只会退出日志查看，不会停止服务。不要把 .env、API Key 或 MCP Token 发到聊天、截图或提交到 Git。

Dify 1.15.0

在 Dify 的 MCP 工具提供方中：

1. Streamable HTTP 填 https://你的域名/mcp；旧配置可填 /sse。

2. Header 填 Authorization: Bearer <MY_IMAGE_MCP_TOKEN>。

3. timeout 建议 180 秒，SSE read timeout 建议 300 秒。

4. binary 工作流调用时使用 delivery: inline 或 auto。

模板见 examples/workflows/dify-mcp-provider.json。Dify 1.15.0 会把 image 解码成 blob，把 structuredContent 转成工作流变量；其适配器会忽略 resource_link，所以不要为 Dify 使用 delivery: link。

n8n 2.30.5

普通 MCP Client 节点：

1. Transport 选择 HTTP Streamable，URL 填 https://你的域名/mcp。

2. 使用 Bearer Auth，timeout 填 180000 ms。

3. 保持 Convert to Binary 开启，并使用 delivery: inline 或 auto。

AI Agent 的 MCP Client Tool 会优先把 structuredContent 交给模型，因此服务会在其中返回原图 uri、path、尺寸和 MIME，不把 Base64 塞进模型上下文。示例见 examples/workflows/n8n-mcp-client.json 和 examples/workflows/n8n-mcp-client-tool.json。

兼容性证据

“兼容 MCP”不等于每个聊天 UI 都以同样方式内联显示图片。多重结果合同保证不能内联时仍有元数据、路径或下载链接。

开发与验证

npm ci
npm run check
npm run test:compat
npm run test:examples
npm pack --dry-run

npm run test:compat 的 Dify 测试需要 uv；它会使用 Python 3.12 和固定的 Pydantic 2.12.5。兼容快照的版本、提交、包完整性和 SHA-256 记录在 compat/manifest.json。

安全配置

常用高级变量见 .env.example。重点：

• MY_IMAGE_ALLOWED_INPUT_DIRS：允许读取本地编辑图片的目录。macOS/Linux 用 : 分隔，Windows 用 ;。

• MY_IMAGE_ALLOW_PRIVATE_NETWORK_URLS=false：默认阻止 URL 输入访问内网、回环和保留地址。

• MY_IMAGE_ALLOW_INSECURE_REMOTE_HTTP=false：远程图片默认只允许 HTTPS。

• MY_IMAGE_ALLOW_INSECURE_HTTP=false：上游 Base URL 的明文 HTTP 默认只允许 localhost。

• 不要提交 .env、用户配置文件、API Key 或 MCP token。

License

项目使用 MIT。compat/vendor 中的上游兼容测试快照保留各自许可证，详见该目录。