imageat

@imageat/mcp

适用于 ImageAT 的模型上下文协议（MCP）服务。为任何 MCP 客户端（Claude Desktop、Cursor 等）提供生成图像、生成视频和使用 ImageAT 图像编辑功能的工具——费用从你的 ImageAT 账户中扣除。

计费。 如果你有有效订阅，MCP 请求会按与 imageat.com 相同的费率使用网站额度——同一次生成无论通过哪种方式，费用都相同。网站额度用完后（或如果你没有订阅），请求将按 API 价格从预付费 API 余额中扣款。连接客户端需要两者之一。

工具

工具	功能
imageat_generate_image	文本生成图像 / 图像生成图像。返回 CDN 图像 URL。
imageat_generate_video	文本生成视频 / 图像生成视频。返回 CDN mp4 URL。
imageat_generate_video_task	实验性的 MCP Tasks 版本，支持 tasks/get 和 tasks/result。
imageat_check_video_status	检查异步视频生成状态，直到生成完成。
imageat_ask_gemini_argon	向 Google 的 Gemini 4 Argon 提问（可选图像 URL，并支持 Google Search / Maps grounding）。返回文本答案。
imageat_check_credits	当前预付费 API 余额（USD）。
imageat_game_guide	从这里开始制作可玩的浏览器游戏：工作流、运行时规则和套件 API（Phaser 2D / three.js 3D）。免费。
imageat_search_game_models	搜索 2,700 多个适用于游戏的 3D 库模型；返回带动画的 library_key。免费。
imageat_generate_game_asset	生成单个游戏素材：精灵、背景、纹理、徽标或由 AI 制作的 3D hero_model。返回 asset_id。
imageat_publish_game	检查游戏代码，将其与引擎和素材打包，并返回可分享的游戏链接。
imageat_update_game	将你的某个游戏的新代码作为新版本发布（链接不变）。免费。
imageat_edit_<feature>	每种编辑功能对应一个工具，启动时实时获取——例如 imageat_edit_remove-background、imageat_edit_object-eraser、imageat_edit_relight、imageat_edit_virtual-try-on、imageat_edit_city-teleport、imageat_edit_ai-edit-pro。新功能会自动出现。

如果启动时无法访问功能目录，则会注册一个通用的 imageat_edit_image 工具（接收 feature ID 参数）作为替代，以确保服务仍可正常工作。

工具结果同时包含易读文本和带类型的 structuredContent。工具架构、安全注解和输出架构可让 Agent 客户端验证调用，并区分只读工具。

资源和提示词

• imageat://account/credits — 实时预付费 API 余额（USD）。
• imageat://edit/features — 实时编辑功能目录。
• imageat://models/images 和 imageat://models/videos — 媒体模型目录。
• imageat://generations/recent — 账户最近生成的十项内容。
• create-product-visual — 可复用的产品图像工作流提示词。
• animate-image — 可复用的图像转视频工作流提示词。
• create-social-campaign、generate-and-upscale、create-creative-variants — 营销活动工作流。

设置

1. 在 ImageAT 的 Projects 页面创建 API 密钥（以 iat_live_ 开头）。
2. 将服务添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "imageat": {
      "command": "npx",
      "args": ["-y", "@imageat/mcp"],
      "env": {
        "IMAGEAT_API_KEY": "iat_live_xxxxxxxxxxxx"
      }
    }
  }
}

3. 重启客户端。现在即可使用 imageat_* 工具。

环境变量

变量	必填	默认值	说明
IMAGEAT_API_KEY	是	—	你的 iat_live_ 密钥。
IMAGEAT_BASE_URL	否	https://imageat.com	提供 /api/v1/* 生成端点的 Web 应用。用于本地开发时，设置为 http://localhost:3000。

远程服务（claude.ai、ChatGPT、其他网页客户端）

上面的 npx 配置使用 stdio——适用于可启动本地进程的桌面应用 （Claude Desktop、Cursor、Claude Code）。claude.ai 和 chatgpt.com 等浏览器客户端 则会通过 Streamable HTTP 连接到远程 MCP 端点。

同一组工具也可通过 dist/http.js 以 HTTP 方式提供。每个 MCP 会话都会通过 Authorization: Bearer iat_live_... 标头携带用户自己的 API 密钥（支持多用户），因此可以将此端点 配置到托管连接器中。

# Run the remote server locally against a local ImageAT instance:
IMAGEAT_BASE_URL=http://localhost:3000 PORT=8787 npm run start:http
# MCP endpoint: http://localhost:8787/mcp   ·   health: /health

使用随附的 Dockerfile 部署（例如在 Dokploy 上部署为 mcp.imageat.com），然后将其添加为 自定义连接器：

• claude.ai — Settings → Connectors → Add custom connector → URL https://mcp.imageat.com/mcp。
• ChatGPT — Connectors / Developer mode → 添加服务器 URL https://mcp.imageat.com/mcp。

浏览器客户端会运行 OAuth 流程：添加连接器后，它们会打开由此服务提供的授权页面，供你粘贴 iat_live_ 密钥；随后客户端会收到与该密钥绑定的短期访问令牌。非浏览器客户端（mcp-remote、MCP Inspector、curl）仍可直接通过 Authorization: Bearer iat_live_... 发送原始 iat_live_ 密钥。

OAuth 层（src/oauth.ts）提供 RFC 8414/9728 发现文档、RFC 7591 动态客户端注册，以及 PKCE /authorize + /token。有效期有限的访问令牌和刷新令牌使用 MCP_OAUTH_SECRET 通过 AES-256-GCM 加密；刷新令牌在使用后会轮换，/revoke 会使已签发的令牌失效。OAuth 令牌与其客户端 ID 和请求的作用域绑定。空闲的 MCP 会话会自动回收。

变量	适用范围	默认值	说明
PORT	仅远程	8787	HTTP 监听端口。
IMAGEAT_BASE_URL	两者	https://imageat.com	提供 /api/v1/* 的上游 Web 应用。
MCP_OAUTH_SECRET	仅远程	（每次启动时随机生成）	用于加密已签发 OAuth 令牌的长随机字符串。生产环境中请设置此项，否则每次重启都会使令牌失效。
MCP_PUBLIC_URL	仅远程	根据请求推导	公共源站，例如 https://mcp.imageat.com。仅当代理标头不正确时才需要设置。
MCP_ALLOWED_ORIGINS	仅远程	ChatGPT、Claude、Cursor、VS Code、GitHub、imageat	以逗号分隔的浏览器 Origin 允许列表。不带 Origin 的请求（常见于服务器间客户端）不受影响。
MCP_SESSION_IDLE_MS	仅远程	7200000	回收空闲时长达到此毫秒数的 MCP 会话。
MCP_MAX_SESSIONS	仅远程	500	此进程达到容量上限后，以 503/Retry-After 拒绝新会话。
INTERNAL_SERVICE_KEY	仅远程	—	与 Web 应用共享。用于完成“使用 imageat 登录”，并为 ChatGPT 个人资料的调用签名，以便扣除网站积分。
OPENAI_APPS_CHALLENGE	仅远程	—	来自 OpenAI 插件提交的域名验证令牌，以原始内容形式在 /.well-known/openai-apps-challenge 提供。

ChatGPT 应用配置（/chatgpt/mcp）

已发布的 ChatGPT 应用连接到 https://mcp.imageat.com/chatgpt/mcp，而不是 /mcp。它是一个单独的精选配置（src/chatgpt.ts），因为 OpenAI 的目录规则与其他客户端不同：

• 固定的工具列表。 OpenAI 会审核工具，并暂缓批准新工具，因此此配置不会根据实时编辑功能目录生成工具。在此处添加工具意味着它需要等待审核。
• 严格的内容过滤。 上游调用会携带 X-Imageat-Surface: chatgpt，且 Web 应用会对每个请求应用受限账户过滤器（lib/content-restriction.ts）。
• 所有账户均使用网站额度。 ChatGPT 用户无法在应用中购买 API 余额，因此，使用 X-Imageat-Surface-Auth（INTERNAL_SERVICE_KEY 的 HMAC）签名的调用会消耗网站额度（lib/api-credit-mode.ts）。
• 不显示购买提示。 错误文本绝不会链接到定价页面或充值页面。
• 附加照片通过 openai/fileParams 以 { download_url, file_id } 的形式传入。
• 结果会在小组件中呈现（src/widget.ts，MCP Apps ui://imageat/media-v1.html）。视频渲染期间，小组件也会自行轮询 imageat_check_video_status。

应用发布后，如需更改 URL，必须联系 OpenAI 支持。 OAuth 接受 ChatGPT 的客户端 ID 元数据文档（https://chatgpt.com/oauth/client.json），会在授权重定向中返回 iss（RFC 9207），并将令牌绑定到请求的 resource。

本地开发

npm install
npm run build

# Inspect the stdio server with the official MCP Inspector against a local ImageAT instance:
IMAGEAT_API_KEY=iat_live_... IMAGEAT_BASE_URL=http://localhost:3000 \
  npx @modelcontextprotocol/inspector node dist/index.js

安全注意事项

在生产环境中设置一个稳定且足够长的随机 MCP_OAUTH_SECRET。默认情况下会限制浏览器 Origin；将任何可自托管的 Web 客户端添加到 MCP_ALLOWED_ORIGINS。直接的服务端到服务端客户端通常会省略 Origin 标头，并继续使用 iat_live_ Bearer 密钥正常工作。