redfox-ai-gen-mcp

RedFoxHub AI 生成 MCP Server — 将 GPT-Image-2 图片、豆包 Seedream 图片（Pro/Lite）、豆包 Seedance 视频生成能力封装为 8 个 MCP 工具，适用于 dsh、Claude Code、Cursor 等任意 MCP 客户端。

工具（8）

异步工具内部自动轮询：提交 → 等待 → 返回完整结果，无需手动处理 taskId。若等待超过 timeout_seconds（图片默认 240 秒、视频默认 480 秒），返回 taskId，可用对应的 result 工具补查。

GPT-Image-2 注意事项：gpt_image_generate 返回的 imageUrls 有效期仅数分钟，过期后访问返回 404，请立即下载保存；任务状态实测为 queued/in_progress/completed/failed（仅后两者为终态）；reference_images 必须是公网可访问且未过期的图片 URL，否则任务会以 failed 结束。实测 1k 单张约 40~60 秒。

认证

1. 前往 https://redfox.hk/settings/api-keys?source=mcp 获取 API Key
2. 设置环境变量：

export REDFOX_API_KEY="YOUR_API_KEY"

未配置 key 时，每个工具都会返回结构化的获取引导。

安装与运行（本地 stdio）

需要 Python ≥ 3.10，推荐使用 uv：

uvx redfox-ai-gen-mcp

或：

pip install redfox-ai-gen-mcp
redfox-ai-gen-mcp

客户端配置

Claude Code：

claude mcp add redfox-ai-gen --env REDFOX_API_KEY=YOUR_API_KEY -- uvx redfox-ai-gen-mcp

Cursor / 其他 MCP 客户端：

{
  "mcpServers": {
    "redfox-ai-gen": {
      "command": "uvx",
      "args": ["redfox-ai-gen-mcp"],
      "env": { "REDFOX_API_KEY": "YOUR_API_KEY" }
    }
  }
}

远程 HTTP 模式（多租户）

适用于 MCP 市场与托管场景，每个用户携带自己的 API Key：

redfox-ai-gen-mcp --transport http --host 0.0.0.0 --port 8000
# 或环境变量：REDFOX_MCP_TRANSPORT=http REDFOX_MCP_HOST=0.0.0.0 REDFOX_MCP_PORT=8000

• MCP 端点：http://<host>:8000/mcp（Streamable HTTP）；健康检查：GET /health
• 每个请求通过请求头 REDFOX_API_KEY: <key>（或 Authorization: Bearer <key>）携带自己的 key，按 key 建独立客户端缓存，额度互不共享

客户端配置（远程 URL + 请求头）：

{
  "mcpServers": {
    "redfox-ai-gen": {
      "url": "http://<host>:8000/mcp",
      "headers": { "REDFOX_API_KEY": "ak_your_key" }
    }
  }
}

Docker 部署

本包目录自带 Dockerfile，可独立构建部署：

cd packages/redfox-ai-gen-mcp
docker build -t redfox-ai-gen-mcp .
docker run -d -p 8000:8000 redfox-ai-gen-mcp

镜像不内置任何 API Key，调用方通过请求头携带自己的 key。

底层实现

基于官方 SDK redfox-python-sdk。API 文档：https://redfox.hk/?source=mcp。

License

MIT