SiliconFlow Image Generator MCP Server

一个功能强大的 Model Context Protocol (MCP) 服务器，通过 SiliconFlow API 实现高质量的图片生成。

✨ 功能特性

• 🎨 多模型支持 - 支持 Qwen、Flux 等多种图片生成模型
• 🚀 高性能 - 内置请求队列和并发控制（最多3个并发请求）
• 🔄 智能重试 - 自动重试机制（最多3次），采用指数退避策略
• 📁 自动保存 - 自动下载并保存生成的图片到本地文件系统
• ✅ 参数验证 - 完善的输入验证，包括文件名、扩展名、尺寸等
• 📊 详细日志 - 开发模式下提供详细的日志输出
• 🛡️ 错误处理 - 智能错误分类和处理，区分客户端错误和服务器错误
• 📦 灵活安装 - 支持 npm 全局安装、npx 直接使用和本地开发

📋 系统要求

• Node.js: >= 18.0.0
• npm 或 yarn
• SiliconFlow API Key（从 SiliconFlow 官网 获取）

🚀 安装和设置

方法 1: 通过 npm 全局安装（推荐）

npm install -g @siliconflow/mcp-image-generator

方法 2: 通过 npx 直接使用（无需安装）

npx @siliconflow/mcp-image-generator

方法 3: 本地开发安装

git clone https://github.com/siliconflow/mcp-image-generator.git
cd mcp-image-generator
npm install

⚙️ 配置 MCP 服务器

1. 获取 SiliconFlow API Key

1. 访问 SiliconFlow 官网
2. 注册或登录账户
3. 进入控制台，在 API Keys 页面创建新的 API Key
4. 复制生成的 API Key（格式类似：sk-xxxxxxxxxxxx）

2. 配置 MCP 服务器

在您的 MCP 配置文件中（通常是 ~/.config/claude/settings.json 或类似路径），添加以下配置：

使用 npm 全局安装版本：

{
  "mcpServers": {
    "siliconflow-images": {
      "command": "siliconflow-image-gen",
      "args": [],
      "env": {
        "SILICONFLOW_API_KEY": "your_siliconflow_api_key_here"
      }
    }
  }
}

使用 npx 版本：

{
  "mcpServers": {
    "siliconflow-images": {
      "command": "npx",
      "args": ["-y", "@siliconflow/mcp-image-generator"],
      "env": {
        "SILICONFLOW_API_KEY": "your_siliconflow_api_key_here"
      }
    }
  }
}

使用本地开发版本：

{
  "mcpServers": {
    "siliconflow-images": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-image-generator/index.js"],
      "env": {
        "SILICONFLOW_API_KEY": "your_siliconflow_api_key_here"
      }
    }
  }
}

3. 验证配置

配置完成后，重启您的 MCP 客户端（如 Claude Desktop），服务器应该会自动连接并可用。

📖 使用方法

配置完成后，在支持 MCP 的客户端中，您可以使用以下工具：

generate_image

根据文本提示词生成图片并保存到本地文件系统。

参数说明

参数	类型	必需	默认值	说明
prompt	string	✅	-	描述想要生成的图片的详细提示词（建议100-800字符，英文效果更佳）
filename	string	✅	-	保存的文件名，必须包含扩展名（如 blog-cover-01.png）
output_dir	string	❌	./images	图片保存的相对路径（相对于当前工作目录）
model	string	❌	Qwen/Qwen-Image	使用的模型名称
image_size	string	❌	1664x928	图片尺寸

支持的文件扩展名

• .jpg / .jpeg
• .png
• .webp

支持的图片尺寸

• 1024x1024 - 正方形
• 720x1280 - 竖屏
• 1280x720 - 横屏
• 1664x928 - 宽屏（默认）

支持的模型

• Qwen/Qwen-Image（默认）
• black-forest-labs/FLUX.1-schnell
• black-forest-labs/FLUX.1-dev
• 以及其他 SiliconFlow 支持的图片生成模型

使用示例

示例 1: 生成博客封面

生成一张关于"科技未来感城市夜景"的博客封面图片，文件名为"tech-city-cover.png"

示例 2: 生成头像

生成一个可爱的卡通猫咪头像，文件名为"cat-avatar.png"，尺寸为1024x1024

示例 3: 生成横幅

生成一张现代简约风格的横幅图片，主题是"数字化转型"，文件名为"digital-banner.png"，尺寸为1280x720

返回结果

成功生成图片后，将返回以下信息：

图片生成成功！
📁 保存路径: /absolute/path/to/images/filename.png
📏 文件大小: 1234 KB
🎨 生成时间: 5.2s
⏱️ 总耗时: 5.3s
🔧 模型: Qwen/Qwen-Image
📐 尺寸: 1664x928

🔧 工作原理

架构流程

用户请求 → MCP 客户端 → MCP 服务器 → SiliconFlow API
                                    ↓
                              图片生成
                                    ↓
                              下载图片
                                    ↓
                              保存到本地
                                    ↓
                              返回结果

核心组件

1. 请求队列管理器 (RequestQueue)

   • 控制并发请求数量（默认最多3个）
   • 防止 API 速率限制
   • 优化资源使用

2. 图片生成器 (ImageGenerator)

   • 参数验证
   • API 调用
   • 图片下载
   • 文件保存

3. 日志记录器 (Logger)

   • 开发模式下输出详细日志
   • 记录操作过程和错误信息

性能优化

• 并发控制: 最多3个并发请求，避免 API 速率限制
• 自动重试: 最多3次重试，采用指数退避策略（1s, 2s, 4s）
• 智能错误处理: 区分客户端错误（4xx）和服务器错误（5xx）
• 文件大小统计: 自动计算并显示文件大小

🛠️ 开发信息

项目结构

mcp-image-generator/
├── index.js              # 主程序文件
├── package.json          # 项目配置
├── README.md            # 项目文档
├── LICENSE              # MIT 许可证
└── .gitignore           # Git 忽略文件

依赖项

包名	版本	用途
@modelcontextprotocol/sdk	^1.0.4	MCP SDK
axios	^1.7.9	HTTP 请求库
dotenv	^16.4.7	环境变量管理

环境变量

变量名	必需	说明
SILICONFLOW_API_KEY	✅	SiliconFlow API 密钥
NODE_ENV	❌	环境模式（设置为 development 可启用详细日志）

开发模式

启用开发模式以查看详细日志：

NODE_ENV=development siliconflow-image-gen

或在 MCP 配置中添加：

{
  "env": {
    "SILICONFLOW_API_KEY": "your_api_key",
    "NODE_ENV": "development"
  }
}

⚠️ 注意事项

1. API Key 安全

   • 不要将 API Key 提交到版本控制系统
   • 定期轮换 API Key
   • 使用环境变量管理敏感信息

2. 文件命名

   • 文件名必须包含扩展名
   • 避免使用特殊字符：< > : " / \ | ? *
   • 建议使用有意义的文件名

3. 提示词优化

   • 英文提示词通常效果更好
   • 建议长度：100-800 字符
   • 最大长度：8000 字符
   • 描述越详细，生成效果越好

4. 性能考虑

   • 图片生成通常需要 5-30 秒
   • 并发请求受限于 API 速率限制
   • 大尺寸图片生成时间更长

5. 存储空间

   • 确保有足够的磁盘空间
   • 定期清理不需要的图片
   • 默认保存在 ./images 目录

🔍 故障排除

错误：SILICONFLOW_API_KEY 环境变量未设置

症状: 服务器启动失败或工具调用失败

解决方案:

1. 确保在 MCP 配置文件的 env 部分正确设置了 SILICONFLOW_API_KEY
2. 检查 API Key 格式是否正确（通常以 sk- 开头）
3. 重启 MCP 客户端使配置生效

错误：API 请求失败 (401 Unauthorized)

症状: 返回 "API 请求失败 (401): Unauthorized"

解决方案:

1. 检查 API Key 是否正确
2. 确认 API Key 未过期或被撤销
3. 验证 API Key 是否有足够的权限

错误：API 请求失败 (429 Too Many Requests)

症状: 返回 "API 请求失败 (429): Too Many Requests"

解决方案:

1. 减少并发请求数量
2. 等待一段时间后重试
3. 检查账户配额是否已用完

错误：参数验证失败

症状: 返回 "参数验证失败: ..."

解决方案:

1. 检查 prompt 是否为非空字符串
2. 确保 filename 包含有效的扩展名
3. 验证 image_size 是否在支持的尺寸列表中
4. 检查文件名是否包含非法字符

错误：保存文件失败

症状: 返回 "保存文件失败: ..."

解决方案:

1. 检查输出目录的写入权限
2. 确保磁盘空间充足
3. 验证文件名是否包含非法字符
4. 检查路径是否过长

错误：图片生成失败，已尝试 3 次

症状: 返回 "图片生成失败，已尝试 3 次: ..."

解决方案:

1. 检查网络连接是否正常
2. 确认 SiliconFlow API 服务是否可用
3. 验证账户余额是否充足
4. 尝试使用不同的模型或参数

调试技巧

启用开发模式查看详细日志：

{
  "env": {
    "SILICONFLOW_API_KEY": "your_api_key",
    "NODE_ENV": "development"
  }
}

日志将显示：

• API 请求详情
• 响应状态
• 错误信息
• 性能指标

📝 更新日志

v1.0.0 (2024-12-25)

• ✨ 初始版本发布
• 🎨 支持 SiliconFlow API 图片生成
• 🚀 支持多种模型（Qwen、Flux 等）
• 📦 支持 npm 全局安装和 npx 使用
• 🔄 内置请求队列和并发控制
• 🛡️ 完善的错误处理和重试机制
• 📊 详细的日志记录和性能统计
• ✅ 完整的参数验证

🤝 贡献

欢迎提交 Issue 和 Pull Request！

贡献指南

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🔗 相关链接

• SiliconFlow 官网
• SiliconFlow API 文档
• Model Context Protocol
• MCP SDK

💬 支持

如有问题或建议，请：

• 提交 Issue
• 查看 文档
• 联系支持团队

---

Made with ❤️ by SiliconFlow MCP Team