zjzmei-mcp

最美证件照 MCP 服务。让 WorkBuddy、Claude Code 等 MCP 客户端直接制作证件照，并使用换底色、改大小、变清晰、格式转换四个图片工具。

远程服务（推荐）

官方远程端点无需安装任何运行时，Streamable HTTP 客户端直接连接，密钥放在请求头：

{
  "mcpServers": {
    "zjzmei": {
      "type": "streamableHttp",
      "url": "https://zmapi.zjzmei.top/mcp",
      "headers": { "Authorization": "Bearer 你的密钥" }
    }
  }
}

远程服务读不到你电脑上的文件：本地照片先调用 create_upload_link，按返回的命令 curl -F "file=@照片路径" <上传链接> 上传（链接 10 分钟内有效、只能用一次，最大 20MB），再把返回的 assetId 传给制作工具。结果地址 5 分钟内有效，请及时下载。

本地运行（stdio）

需要 uv 和一个 MCP 访问密钥。

ZJZMEI_API_KEY=你的密钥 uvx zjzmei-mcp

也可以用 npm 包启动（内部调用 uvx）：npx -y zjzmei-mcp。

命令行参数：--transport stdio|http（默认 stdio）、--host（默认 127.0.0.1）、--port（默认 8765）、--api-base、--public-base-url、--allowed-hosts。

自托管 HTTP 模式

--transport http 启动 Streamable HTTP 服务（/mcp，无状态、JSON 响应），供远程客户端使用：

• 按请求鉴权：Authorization: Bearer <密钥>（兼容 X-Api-Key），密钥由业务后端判定；缺失或无效返回 401，后端不可用返回 503。进程不需要 ZJZMEI_API_KEY。
• POST /mcp-upload/{token}：create_upload_link 签发的一次性上传入口（multipart 字段 file 或原始图片字节）。令牌存在进程内存，只能单副本部署。
• GET /healthz：健康检查。
• 不读取服务端本地文件，不写 saveDir。--public-base-url 决定上传链接的对外地址；--allowed-hosts 开启 Host 头校验。

客户端配置

{
  "mcpServers": {
    "zjzmei": {
      "command": "uvx",
      "args": ["zjzmei-mcp"],
      "env": { "ZJZMEI_API_KEY": "你的密钥" }
    }
  }
}

工具

图片入参可以是本地文件路径（仅 stdio）、http(s) 图片链接或 assetId，源图仅支持 JPG/PNG。返回的图片地址是短期地址；stdio 模式传 saveDir 可直接保存到本地。

开发

uv sync
uv run pytest
uv build