Qingping AI MCP

青萍AI MCP服务器

青萍AI MCP（Model Context Protocol）服务器，提供文生图和文生视频功能的MCP工具。

功能特性

• ✅ 文生图：根据文本描述生成图片，支持多种尺寸和批量生成
• ✅ 图生图：基于1-4张参考图片和文本提示词生成新图片
• 🔄 自动会话管理：自动创建和管理API会话
• 📥 自动下载：生成的图片/视频自动下载到本地
• ⏱️ 智能轮询：每10秒轮询一次任务状态，避免频繁请求
• 🛡️ 错误重试：网络错误自动重试（最多3次）
• 📊 详细日志：可选的详细日志输出

快速开始

方法一：使用 Claude Code CLI（推荐）

如果您使用 Claude Code CLI，可以直接运行以下命令进行安装：

claude mcp add qingping-ai-mcp npx --env QINGPING_API_KEY= -- -y qingping-ai-mcp

将 `` 替换为您的实际 API 密钥。

方法二：使用 npx（Claude Desktop）

无需安装，直接使用 npx 运行。在Claude Desktop的配置文件中添加：

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

{
  "mcpServers": {
    "qingping-ai": {
      "command": "npx",
      "args": ["-y", "qingping-ai-mcp"],
      "env": {
        "QINGPING_API_KEY": "your_api_key_here"
      }
    }
  }
}

方法三：本地开发

如果您想修改代码或进行本地开发：

# 克隆项目
git clone https://github.com/lusyoe/qingping-ai-mcp.git
cd qingping-ai-mcp

# 安装依赖
npm install

# 构建项目
npm run build

然后在Claude Desktop配置中使用本地版本：

{
  "mcpServers": {
    "qingping-ai": {
      "command": "node",
      "args": ["/absolute/path/to/qingping-ai-mcp/dist/index.js"],
      "env": {
        "QINGPING_API_KEY": "your_api_key_here"
      }
    }
  }
}

环境变量说明

创建 .env 文件或设置环境变量：

# 必需：青萍AI API密钥
QINGPING_API_KEY=your_api_key_here

# 可选：API基础URL（默认：https://img.lusyoe.com/api）
QINGPING_API_BASE_URL=https://img.lusyoe.com/api

# 可选：日志级别（默认：info）
LOG_LEVEL=info

# 可选：下载目录（默认：./downloads）
DOWNLOAD_DIR=./downloads

# 可选：会话文件路径（默认：./data/session.json）
SESSION_FILE=./data/session.json

获取API密钥

按照以下步骤获取 API 密钥：

1. 访问 青萍AI
2. 登录后点击右上角的头像或用户名，进入个人信息页面
3. 滚动到页面最底部，找到 API KEY 区域
4. 点击生成 API KEY 按钮
5. 复制生成的 API 密钥并保存到配置文件中

注意：API 密钥是敏感信息，请妥善保管，不要泄露给他人。

使用方法

配置完成后，重启Claude Desktop，然后您就可以在对话中使用以下功能：

可用工具

1. generate_image - 文生图

根据文本描述生成图片。

参数：

• prompt (string, 必需): 图片生成的文本提示词
• image_size (string, 可选): 图片尺寸比例

- 可选值: auto, 1:1, 16:9, 9:16, 4:3, 3:4 - 默认: auto

• image_count (integer, 可选): 生成的图片数量

- 范围: 1-4 - 默认: 1

• model (string, 可选): 使用的模型

- 默认: google/gemini-2.5-flash-image

返回：

{
  "success": true,
  "task_id": "task_ai_xxx",
  "local_path": "/path/to/image.jpg",
  "cdn_url": "https://img-cdn.lusyoe.com/...",
  "prompt": "你的提示词",
  "image_size": "1:1",
  "image_count": 1,
  "generation_time": 45.2
}

2. generate_image_from_images - 图生图

基于1-4张参考图片和文本提示词生成新图片。

参数：

• prompt (string, 必需): 描述生成内容的文本提示词
• source_image_urls (array, 必需): 参考图片的URL列表

- 范围: 1-4个URL - 每个URL必须是有效的图片链接

• image_size (string, 可选): 图片尺寸比例

- 可选值: auto, 1:1, 16:9, 9:16, 4:3, 3:4 - 默认: auto

• image_resolution (string, 可选): 图片分辨率

- 可选值: 1K, 2K, 4K - 默认: 1K

• image_count (integer, 可选): 生成的图片数量

- 范围: 1-4 - 默认: 1

• model (string, 可选): 使用的模型

- 默认: google/gemini-2.5-flash-image

返回：

{
  "success": true,
  "task_id": "task_ai_xxx",
  "local_path": "/path/to/image.jpg",
  "cdn_url": "https://img-cdn.lusyoe.com/...",
  "prompt": "你的提示词",
  "source_image_urls": ["https://example.com/ref.jpg"],
  "image_size": "auto",
  "image_count": 1,
  "generation_time": 52.3
}

使用场景：

• 风格迁移：保持参考图的艺术风格
• 内容变体：保持主题，生成不同变体
• 构图参考：使用参考图的布局方式
• 多图融合：综合多张参考图的特征
• 图片编辑：去除或修改图片中的特定内容

3. generate_video - 文生视频（暂未实现）

根据文本描述生成视频。

状态： 暂未实现，敬请期待

4. reset_session - 重置会话

重置当前会话，强制创建新的会话ID。

参数： 无

返回：

{
  "success": true,
  "new_session_id": "session_xxx",
  "message": "会话已重置并创建新会话"
}

5. get_video_status - 查询视频状态

查询视频生成任务的状态。

参数：

• task_id (string, 必需): 视频生成任务ID

返回：

{
  "task_id": "task_video_xxx",
  "status": "processing",
  "progress": 45,
  "cdn_url": null,
  "error": null
}

使用示例

示例1：生成单张图片

请使用青萍AI 帮我生成一张图片：一只可爱的橘猫在花园里玩耍，1:1比例

ai-gen-image

可在本地查看，也可以登录官网，进入 AI生图 模块查看：

ai-mcp-session

示例2：生成多张图片

请使用青萍AI 用以下提示词生成3张图片：日落时分的海滩，海浪轻轻拍打沙滩，16:9比例

示例3：图生图（风格迁移）

请使用青萍AI 基于这张图片生成新的图片：https://example.com/image.jpg
提示词：油画风格，更加色彩鲜艳

示例4：图生图（图片编辑）

请使用青萍AI 基于这张图片进行编辑：https://example.com/photo.png
提示词：去除红色框选区域的内容，保持其他部分不变

示例5：图生图（多图融合）

请使用青萍AI 基于以下两张图片生成新图片：
- https://example.com/cat.jpg
- https://example.com/sunset.jpg
提示词：将猫咪置于日落背景中

示例6：重置会话

重置青萍AI的会话

技术规格

轮询配置

• 文生图轮询间隔: 10秒
• 文生图超时时间: 10分钟（600秒）
• 文生视频轮询间隔: 10秒
• 文生视频超时时间: 30分钟（1800秒）

重试策略

• 最大重试次数: 3次
• 重试延迟: 指数退避（1秒、2秒、4秒）

文件存储

生成的文件保存在以下目录：

• 图片: ./downloads/images/
• 视频: ./downloads/videos/

文件命名格式：

• 图片: {task_id}_{index}.{ext}
• 视频: {task_id}.mp4

开发

构建

npm run build

开发模式

npm run dev

直接运行

npm start

错误处理

服务器会处理以下错误情况：

• 缺少API密钥: 启动时检查QINGPING_API_KEY环境变量
• 网络错误: 自动重试最多3次
• 任务超时: 超过配置的超时时间后停止轮询
• 任务失败: 返回详细的错误信息

许可证

MIT

支持

如有问题，请访问 青萍AI文档 或提交Issue。

更新日志

v1.2.0

• 文生图功能添加模型参数支持
• 图生图功能添加模型参数支持
• 统一模型参数配置接口
• 支持自定义模型选择

v1.1.0

• 新增图生图功能（generate_image_from_images）
• 支持1-4张参考图片URL
• 完整的参数验证和错误处理
• 复用现有的轮询和下载机制

v1.0.0

• 初始版本发布
• 支持文生图功能
• 自动会话管理
• 自动文件下载
• 智能轮询机制