即梦 MCP 服务器

一个基于 Model Context Protocol (MCP) 的即梦图像生成 API 服务器，使用官方 TypeScript SDK 构建。

功能特性

🎨 图像生成工具

• generate_image - 图像生成（支持文生图、图生图、多图参考生成）。支持设置尺寸、比例、编辑强度等。
• query_task - 查询任务状态和结果

🔧 辅助功能

• 推荐尺寸配置 - 提供4.0版本的推荐尺寸选项 (1K/2K/4K)
• 水印配置选项 - 支持多种水印位置和语言设置
• 参数验证 - 自动验证图像尺寸、提示词长度等参数
• 并发控制 - 防止API调用冲突
• 集中化日志 - 支持Elasticsearch日志收集和分析

📚 信息资源

• config://jimeng - 即梦API配置信息
• task://{taskId}/status - 任务状态信息

安装

npm install jimeng-image-mcp

环境配置

创建 .env 文件：

JIMENG_ACCESS_KEY=your_access_key_here
JIMENG_SECRET_KEY=your_secret_key_here

# 可选配置
JIMENG_ENDPOINT=https://visual.volcengineapi.com
JIMENG_REGION=cn-north-1
JIMENG_SERVICE=cv
# 日志配置
ES_ENDPOINT=https://your-es-cluster:9200/logs/_doc

配置说明

• 必需配置：

  • JIMENG_ACCESS_KEY: 火山引擎访问密钥ID
  • JIMENG_SECRET_KEY: 火山引擎访问密钥密码

• 可选配置：

  • JIMENG_ENDPOINT: API端点，默认使用官方端点
  • JIMENG_REGION: 区域，默认cn-north-1
  • JIMENG_SERVICE: 服务名，默认cv
  • ES_ENDPOINT: Elasticsearch日志端点，用于集中化日志管理

使用方法

🖼️ 本地文件支持

图生图工具现在支持多种图片输入方式：

本地文件路径：

• 相对路径：./image.jpg, ../images/photo.png
• 绝对路径：/Users/username/Pictures/image.jpg
• 文件协议：file:///path/to/image.jpg

远程URL：

• HTTP/HTTPS链接：https://example.com/image.jpg

自动处理：

• 本地文件会自动读取并转换为base64编码
• 远程URL会直接传递给API
• 支持混合输入（同时使用本地文件和远程URL）

在 Cursor 中配置

在 Cursor 的设置中添加以下 MCP 服务器配置：

{
  "mcpServers": {
    "jimeng": {
      "command": "npx",
      "args": ["jimeng-image-mcp@latest", "serve"],
      "env": {
        "JIMENG_ACCESS_KEY": "your_access_key_here",
        "JIMENG_SECRET_KEY": "your_secret_key_here"
      }
    }
  }
}

作为 MCP 服务器运行

# 构建项目
npm run build

# 运行 MCP 服务器
npm start

在代码中使用

import { JimengMCPServer } from 'jimeng-image-mcp';

const server = new JimengMCPServer({
  accessKey: process.env.JIMENG_ACCESS_KEY!,
  secretKey: process.env.JIMENG_SECRET_KEY!,
  endpoint: process.env.JIMENG_ENDPOINT,
  esEndpoint: process.env.ES_ENDPOINT, // 可选：Elasticsearch日志端点
});

// 启动服务器
await server.run();

CLI 工具

# 安装 CLI 工具
npm install -g jimeng-image-mcp

# 使用 CLI
jimeng-image-mcp --help
jimeng-image-mcp serve  # 启动MCP服务器
jimeng-image-mcp serve --es-endpoint https://your-es:9200/logs/_doc  # 指定ES端点
jimeng-image-mcp test   # 测试配置

MCP 协议支持

本服务器完全支持 MCP 协议规范，包括：

• ✅ 工具调用 (Tools) - 支持所有即梦API功能
• ✅ 资源管理 (Resources) - 配置信息和任务状态
• ✅ 并发控制 - 防止API调用冲突
• ✅ 错误处理 - 完整的错误捕获和报告
• ✅ 类型安全 - TypeScript + Zod 验证
• ✅ 标准传输 - 支持 stdio 和 HTTP 传输

支持的传输方式

• stdio - 命令行工具和本地集成
• HTTP - 远程服务器部署（需要额外配置）

工具调用示例

// 生成图像 (文生图)
const result = await client.callTool({
  name: 'generate_image',
  arguments: {
    prompt: '一只可爱的小猫',
    size: 4194304, // 2048*2048
  },
});

// 生成图像 (图生图/参考图)
const i2iResult = await client.callTool({
  name: 'generate_image',
  arguments: {
    prompt: '将小猫变成小狗',
    image_urls: [
      '/path/to/local-cat.jpg', // 绝对路径
      'https://example.com/cat.jpg', // 远程URL
    ],
    scale: 0.8,
    width: 1024,
    height: 1024,
  },
});

// 查询任务状态
const status = await client.callTool({
  name: 'query_task',
  arguments: {
    task_id: 'task_123',
    req_key: 'jimeng_t2i_v40' // 可选，默认为 jimeng_t2i_v40
  },
});

资源访问示例

// 获取配置信息
const config = await client.readResource({
  uri: 'config://jimeng',
});

// 获取任务状态
const taskStatus = await client.readResource({
  uri: 'task://task_123/status',
});

开发

构建

npm run build

开发模式

npm run dev

代码质量

# 检查代码格式
npm run lint:check
npm run format:check

# 自动修复代码格式
npm run lint:fix

# 单独运行
npm run lint        # ESLint 检查并修复
npm run format      # Prettier 格式化

测试

# 运行所有测试
npm test

# 运行特定测试
npm run test:api
npm run test:local
npm run test:cli

技术架构

• MCP SDK: @modelcontextprotocol/sdk v1.17.3+
• 类型安全: TypeScript + Zod 验证
• 并发控制: 队列式任务处理
• 错误处理: 完整的错误捕获和报告

依赖要求

• Node.js >= 20.0.0
• TypeScript >= 5.0.0

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

相关链接

• Model Context Protocol
• MCP TypeScript SDK
• 即梦 API 文档