Aipic Mcp

AI Picture MCP 服务

一个 Model Context Protocol（MCP）服务，提供专为网页设计工作流打造的 AI 图像生成能力。此服务集成了 Alibaba Cloud DashScope 的 FLUX 模型，可根据英文提示词生成高质量图像，非常适合用于创建占位图、主视觉图、产品模型图及其他网页素材。

🚀 快速开始

npx -y aipic-mcp

✨ 功能

• 🎨 AI 图像生成：使用 DashScope FLUX 模型和自然语言提示词生成高质量图像
• 🖥️ 网页优化输出：自动优化图像，确保压缩和尺寸适合网页使用
• 📏 灵活调整尺寸：支持自定义宽度和高度（默认：1024x1024）
• 📋 Base64 编码：以 Base64 格式返回图像，可直接用于网页应用
• ⚡ 智能文件保存：优先自动保存到桌面，不可用时则保存到临时目录
• 🔄 异步处理：使用 DashScope 的异步任务 API，确保图像生成可靠
• 🛡️ 稳健的错误处理：全面处理 API 问题、网络问题和无效输入
• 🔐 环境变量支持：通过 DASHSCOPE_API_KEY 或 MODELSCOPE_API_KEY 配置 API 密钥

📦 安装与使用

选项 1：NPX（推荐）

无需安装，直接使用 NPX：

npx -y aipic-mcp

Claude Desktop 配置：

{
  "mcpServers": {
    "aipic": {
      "command": "npx",
      "args": ["-y", "aipic-mcp"]
    }
  }
}

选项 2：使用 API 密钥环境变量的 NPX（推荐）

为获得最佳体验，请将 DashScope API 密钥配置为环境变量：

{
  "mcpServers": {
    "aipic": {
      "command": "npx",
      "args": ["-y", "aipic-mcp"],
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here"
      }
    }
  }
}

使用完整 PATH（如果使用 NVM 或自定义 Node 安装）：

{
  "mcpServers": {
    "aipic": {
      "command": "/Users/your-username/.nvm/versions/node/v20.19.4/bin/npx",
      "args": ["-y", "aipic-mcp"],
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here",
        "PATH": "/Users/your-username/.nvm/versions/node/v20.19.4/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

选项 3：全局安装

npm install -g aipic-mcp

Claude Desktop 配置：

{
  "mcpServers": {
    "aipic": {
      "command": "aipic-mcp"
    }
  }
}

使用 API 密钥环境变量：

{
  "mcpServers": {
    "aipic": {
      "command": "aipic-mcp",
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here"
      }
    }
  }
}

选项 4：本地开发

如果你想为项目做贡献或进行自定义：

1. 克隆此仓库：

git clone https://github.com/leonaries/aipic-mcp.git
cd aipic-mcp

2. 安装依赖：

npm install

3. 构建 TypeScript 代码：

npm run build

4. 在本地测试：

npm run dev

本地开发的 Claude Desktop 配置：

{
  "mcpServers": {
    "aipic": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/Users/your-username/path/to/aipic-mcp",
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here"
      }
    }
  }
}

注意：将 /Users/your-username/path/to/aipic-mcp 替换为你克隆仓库的实际路径。

⚙️ 配置

Claude Desktop 设置

将服务添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

根据你的安装方式，选择上方的某个配置选项。

DashScope API 密钥

使用此服务需要 Alibaba Cloud 提供的 DashScope API 密钥。请前往 Alibaba Cloud DashScope 获取。

获取 API 密钥的步骤：

1. 访问 Alibaba Cloud DashScope
2. 注册或登录你的账户
3. 前往 API 密钥页面
4. 创建具有图像生成权限的新 API 密钥
5. 复制 API 密钥（格式：sk-xxxxxxxxxx）

提供 API 密钥的两种方式：

1. 环境变量（推荐）：按照上文所示，在 Claude Desktop 配置中进行设置
2. 运行时参数：调用工具时传入 API 密钥（不太方便，但更灵活）

🎯 使用

此服务提供一个主要工具：

generate_web_image

生成针对网页设计用途优化的 AI 图像。

参数：

• prompt（必填）：对要生成的图像的英文描述
• apiKey（可选）：你的 DashScope API 密钥（如果未通过 DASHSCOPE_API_KEY 环境变量设置）
• width（可选）：图像宽度，单位为像素（默认值：1024）
• height（可选）：图像高度，单位为像素（默认值：1024）
• outputPath（可选）：用于保存图像的自定义路径（默认值：自动保存到桌面或临时目录）

提示词示例：

• “带有笔记本电脑和咖啡杯的现代简约办公室工作空间”
• “蓝紫色渐变的抽象几何背景”
• “明亮会议室中的专业团队会议”
• “白色背景上的无线耳机电商产品照片”
• “日出时分山景的主视觉图”

在 Claude 中的用法示例（已配置环境变量）：

Generate a hero image for my website with the prompt "A sleek modern smartphone floating above a city skyline at dusk"

在 Claude 中的用法示例（手动提供 API 密钥）：

Generate a hero image for my website with the prompt "A sleek modern smartphone floating above a city skyline at dusk" using my DashScope API key "sk-your-api-key-here"

🔧 API 集成详情

此服务使用 Alibaba Cloud DashScope API，配置如下：

• 模型：flux-schnell（FLUX.1 schnell 模型，可快速生成图像）
• 端点：https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
• 身份验证：Bearer 令牌（你的 DashScope API 密钥）
• 模式：异步处理并轮询任务状态
• 超时时间：生成 5 分钟，下载 30 秒

🛡️ 错误处理

此服务可处理多种错误情况：

• API 密钥无效或缺失
• DashScope API 的速率限制
• 网络超时和连接问题
• 任务生成失败
• 图像下载失败
• 保存图像时发生文件系统错误

🔨 开发

在开发模式下运行

npm run dev

构建生产版本

npm run build

测试

npm test

发布到 NPM

此项目已发布到 NPM。维护者请执行以下操作：

npm run build
npm version patch  # or minor/major
npm publish

🤝 贡献

欢迎贡献！欢迎提交 Pull Request。对于重大更改，请先创建 issue，讨论你希望进行的更改。

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 将更改推送到分支（git push origin feature/AmazingFeature）
5. 创建 Pull Request

🔒 安全注意事项

• 可通过环境变量配置 API 密钥，以提高安全性
• 图像会保存在当前工作目录下的本地文件系统中
• 网络请求设有适当的超时时间，以防止请求挂起
• 输入验证可防止提示词为空或缺少必填参数
• 与硬编码密钥相比，使用环境变量更加安全

📚 依赖项

• @modelcontextprotocol/sdk：用于实现服务的 MCP SDK
• axios：用于 API 请求的 HTTP 客户端
• sharp：图像处理和优化
• uuid：用于生成文件名的唯一 ID

🐛 故障排除

常见问题

1. “找不到命令”错误

   • 确保已安装 Node.js 18+
   • 尝试运行 npx -y aipic-mcp，而不是全局安装
   • 如果使用 NVM，请在配置中指定 npx 的完整路径

2. API 密钥错误

   • 验证 DashScope API 密钥是否有效（应以 sk- 开头）
   • 检查 Alibaba Cloud 账户是否有足够的配额
   • 确保已将 API 密钥正确配置为 DASHSCOPE_API_KEY 环境变量
   • 确保 API 密钥具有图像生成权限

3. 图像生成超时

   • 对于复杂的提示词，DashScope API 可能需要 2-3 分钟
   • 尝试使用更简单的提示词
   • 检查网络连接

4. 环境变量不起作用

   • 更新配置后，重启 Claude Desktop
   • 验证配置文件中的 JSON 语法
   • 检查 API 密钥中是否有多余的空格或引号

5. NPX 安装问题

   • 使用 -y 标志自动确认安装
   • 如果使用 NVM，请确保配置中的 PATH 设置正确

6. 任务生成失败

   • 服务使用异步处理，因此可能需要稍等片刻
   • 查看控制台日志中的详细错误消息
   • 为获得最佳效果，请确保提示词使用英语

📄 许可证

MIT 许可证 — 详情请参阅 LICENSE 文件。

🔗 链接

• NPM 软件包：https://www.npmjs.com/package/aipic-mcp
• GitHub 仓库：https://github.com/leonaries/aipic-mcp
• Alibaba Cloud DashScope：https://dashscope.aliyun.com/
• Model Context Protocol：https://modelcontextprotocol.io/

📝 更新日志

v1.0.4（最新版本）

• 📝 文档更新：全面改进 README，增强功能说明
• 🔧 API 密钥格式：更新所有示例，为 DashScope API 密钥使用正确的 sk- 前缀
• 🌐 环境变量：明确优先使用 DASHSCOPE_API_KEY，而非旧版 MODELSCOPE_API_KEY
• ✨ 用户体验：改进安装指南和故障排除文档

v1.0.3

• ⚡ 智能文件保存：尽可能自动将图像保存到桌面，否则保存到临时目录
• 🔧 增强的环境变量：优先支持 DASHSCOPE_API_KEY，同时向后兼容 MODELSCOPE_API_KEY
• 🛡️ 改进的错误处理：提供更好的错误消息，并增强 API 集成的健壮性
• 📁 智能路径检测：自动创建目录并提供回退机制
• 🚀 更好的用户体验：现在默认将图像直接保存到用户的桌面

v1.0.1

• 🔧 重大变更：改为使用 Alibaba Cloud DashScope API，而非 ModelScope API
• ✨ 添加异步任务处理，提高图像生成的可靠性
• 🐛 修复 API 身份验证问题
• 📚 更新文档以反映 DashScope 集成

v1.0.0

• 🎉 首次发布，集成 ModelScope

---

🌟 如果觉得这个仓库有用，请为它点亮星标！