Image Generation MCP Server

图像生成 MCP 服务

这是一个模型上下文协议（MCP）服务，可让兼容的客户端（如 Cline、Claude Desktop 等）使用 OpenAI 的 API（gpt-image-1、dall-e-3、dall-e-2）生成图像。

它提供了一个 create_image 工具，可接收文本提示词和其他参数，生成图像并将其保存到指定项目的 public 目录中。

功能

• 使用 OpenAI 模型（gpt-image-1、dall-e-3、dall-e-2）根据文本提示词生成图像。
• 使用参考图像和 OpenAI 的 gpt-image-1 模型编辑和组合现有图像。
• 支持通过 brandSignature 参数指定可选的品牌指南。
• 可指定图像尺寸、质量和背景类型（透明或不透明）。
• 通过 styleDefinitionJSON 参数支持统一的视觉风格。
• 将生成的图像保存到由大模型客户端指定的目标项目目录。
• 在源代码（src/index.ts）中提供详细文档，指导大模型如何使用。
• 提供单元测试以供验证。

先决条件

1. Node.js： 推荐使用 18 或更高版本。
2. npm： 随 Node.js 一起安装。
3. OpenAI API 密钥： 你需要一个 OpenAI API 密钥。访问 platform.openai.com/api-keys 创建密钥。请注意，使用 gpt-image-1 可能需要通过 API 组织验证。

安装

选项 1：通过 NPX 安装（推荐）

安装和使用图像服务最简单的方式是使用 NPX。每次重启服务时，此方式都会自动获取更新：

# You don't need to install or clone anything - just run this command to test
npx -y @dfeirstein/image-server@latest

NPX 会从 npm 下载最新版本并运行。每次启动服务时都会自动更新。

选项 2：克隆代码仓库

如果你希望完整访问源代码或想要参与贡献：

1. 克隆代码仓库：

   git clone <repository-url> image-mcp-server
   cd image-mcp-server
   

   （在 GitHub 等平台托管后，将 <repository-url> 替换为实际 URL。）

2. 安装依赖项：

   npm ci
   

   此命令会从 package-lock.json 安装指定的版本，确保依赖项保持一致。

3. 构建服务：

   npm run build
   

   此命令会将 TypeScript 代码编译为 JavaScript，并输出到 dist 目录。

MCP 客户端配置

要通过 MCP 客户端使用此服务，你需要将其配置添加到客户端的设置文件中。具体文件路径取决于客户端：

• Cline（VS Code 扩展）： /Users/<YourUsername>/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json（macOS）
• Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS） （Windows/Linux 上的路径可能不同，请查阅客户端文档。）
• 其他客户端（Roo、Cursor、Windsurf 等）： 请查阅相应客户端的文档，了解其 MCP 设置文件的位置。

将以下配置块添加到客户端设置文件中主 "mcpServers": { ... } 对象内。请务必将占位符替换为你的实际绝对路径和 API 密钥。

使用 NPX 安装（推荐）

// Inside "mcpServers": { ... } in your client's settings JSON file:

"image-mcp-server": {
  "command": "npx",
  "args": [
    "-y",                          // Auto-accept installation
    "@dfeirstein/image-server@latest"     // Always fetch the latest version
  ],
  "cwd": "/tmp",                   // Any temporary directory is fine
  "env": {
    // IMPORTANT: Replace with your actual OpenAI API Key
    "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  // --- Standard MCP Settings ---
  "disabled": false,
  "autoApprove": [],      // List tool names to auto-approve (e.g., ["create_image"])
  "transportType": "stdio",
  "timeout": 60
}

// Make sure to add a comma before this block if it's not the first server listed!

每次 MCP 客户端启动时，此配置都会自动下载并运行最新版本的服务，确保你始终使用最新功能和错误修复。

使用基于代码仓库的安装方式

// Inside "mcpServers": { ... } in your client's settings JSON file:

"image-mcp-server": {
  "command": "node",
  "args": [
    // IMPORTANT: Use the ABSOLUTE path to the built index.js file
    "/path/to/your/cloned/image-mcp-server/dist/index.js"
  ],
  // IMPORTANT: Use the ABSOLUTE path to the server's root directory
  "cwd": "/path/to/your/cloned/image-mcp-server",
  "env": {
    // IMPORTANT: Replace with your actual OpenAI API Key
    "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  // --- Standard MCP Settings ---
  "disabled": false,
  "autoApprove": [],
  "transportType": "stdio",
  "timeout": 60
}

// Make sure to add a comma before this block if it's not the first server listed!

主要配置项：

• 将 /path/to/your/cloned/image-mcp-server 替换为克隆此代码仓库所在位置的绝对路径。
• 将 sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 替换为你的实际 OpenAI API 密钥。
• 确保 disabled 为 false，以启用服务。

MCP 客户端应会自动检测更改并连接到服务。

工具用法（create_image）

安装并配置后，服务将提供 create_image 工具。

访问文档资源

服务将文档作为 MCP 资源公开，LLM 可在编写提示词前访问这些资源：

<access_mcp_resource>
<server_name>image-mcp-server</server_name>
<uri>docs/prompt-recipes</uri>
</access_mcp_resource>


<access_mcp_resource>
<server_name>image-mcp-server</server_name>
<uri>docs/readme</uri>
</access_mcp_resource>

这样，LLM 就能在编写图像提示词前阅读提示词配方文档，从而获得更好的结果。

• 描述： 根据文本提示词生成新图像，可选择应用品牌标识或使用风格定义 JSON，并将图像保存到目标项目的 public 文件夹。也可通过提供参考图像来编辑或组合现有图像。
• 详细用法和参数： 关于参数（prompt、filename、targetProjectDir、brandSignature、styleDefinitionJSON、model、size、quality、background、referenceImagePaths 等）的完整详情，以及 LLM 如何有效使用此工具的指南，请参阅此仓库中 src/index.ts 文件顶部的详细文档注释块。
• 背景选项： background 参数接受 transparent 或 opaque（默认值）两种值。透明背景适用于徽标、图标和叠加层，且与 gpt-image-1 模型搭配效果最佳。透明背景需要使用 PNG 或 WebP 格式。
• 图像编辑： 提供 referenceImagePaths（相对于目标项目 public 文件夹的路径数组）时，工具将使用 OpenAI 的图像编辑功能，根据提示词修改或组合这些图像。对于图像编辑操作，模型会自动设为 gpt-image-1。
• 风格定义： 可选的 styleDefinitionJSON 参数可用于为多张图像定义统一的视觉风格。这对于创建具有统一美学风格的主题图像集尤其有用。JSON 结构会在提示词中直接传递给图像模型，从而支持灵活且丰富的风格定义。
• 输出： 成功时返回包含 { ok: true, path: "relative/path/to/image.png", operation: "edit"|"generate", ... } 的 JSON 对象，其中 path 相对于请求中提供的 targetProjectDir 的 public 文件夹。

curl 测试示例（手动启动服务进行测试后）：

# First, build and start the server from its directory:
# npm run build && node dist/index.js

# In another terminal:
curl -X POST http://localhost:5050/createImage \
  -H 'Content-Type: application/json' \
  -d '{
        "prompt": "A cute otter mascot",
        "filename": "otter-mascot.png",
        "targetProjectDir": "/path/to/your/target/project"
      }'

# Example with background parameter for transparent PNG:
curl -X POST http://localhost:5050/createImage \
  -H 'Content-Type: application/json' \
  -d '{
        "prompt": "A professional logo of a cloud with lightning bolt",
        "filename": "cloud-logo.png",
        "model": "gpt-image-1",
        "background": "transparent",
        "targetProjectDir": "/path/to/your/target/project"
      }'

# Example with image editing and transparent background:
curl -X POST http://localhost:5050/createImage \
  -H 'Content-Type: application/json' \
  -d '{
        "prompt": "Add a glowing blue aura effect around the object",
        "filename": "enhanced-icon.png",
        "model": "gpt-image-1",
        "background": "transparent",
        "referenceImagePaths": ["existing-icon.png"],
        "targetProjectDir": "/path/to/your/target/project"
      }'

# Example with styleDefinitionJSON parameter:
curl -X POST http://localhost:5050/createImage \
  -H 'Content-Type: application/json' \
  -d '{
        "prompt": "Abstract representation of Litigation",
        "filename": "litigation-concept.png",
        "targetProjectDir": "/path/to/your/target/project",
        "styleDefinitionJSON": {
          "output_requirements": {
            "color_mode": "Full Vibrant Color Photography", 
            "style": "Abstract Conceptual Realism",
            "quality": "High-end Professional Photo Shoot"
          },
          "color_palette": {
            "primary_accent": {"name": "Primary Blue", "hex": "#1474F3"},
            "supporting_colors": [
              {"name": "Deep Navy", "hex": "#1C2B4A"},
              {"name": "Warm Neutral", "hex": "#E8D7C1"}
            ],
            "overall_tone": "Predominantly cool with warm accents"
          },
          "strict_exclusions": [
            "No Black and White or Monochrome output",
            "No Text or Writing"
          ]
        }
      }'

（注意：仅在直接运行时，服务才会监听端口 5050；通过 MCP stdio 启动时不会监听该端口。）

开发

如果你想为服务做出贡献或对其进行修改：

• 运行开发服务： npm run dev（使用 tsc -w 和 nodemon 自动重新编译并重启）
• 运行测试： npm test（使用 vitest）

Docker 支持

此仓库包含一个用于构建服务容器映像的 Dockerfile。这有助于确保运行环境一致，也适用于潜在的部署场景，但通过 node 与标准 MCP 客户端集成时并不需要它。

构建 Docker 映像：

# Navigate to the project directory
cd image-mcp-server
# Build the image
docker build -t image-mcp-server:latest .

（需要安装并运行 Docker Desktop 或 Docker Engine。）

运行容器（示例，不适用于 MCP stdio）：

docker run -d --name image-server -e OPENAI_API_KEY="your_api_key" image-mcp-server:latest

（注意：像这样通过 docker run 运行，无法直接与需要通过 stdio 通信的 MCP 客户端配合使用。主要安装方式仍是按上述说明配置客户端，使其运行 node dist/index.js。）

许可证

（在此处添加你选择的许可证，例如 MIT License）