Skip to content

genoooool/mcp-image-generator

BranchesTags

Repository files navigation

@genoooool/mcp-image-generator

This is an MCP (Model Context Protocol) server for AI image generation with multi-provider support.

Features

  • Multi-provider support: Switch between Yunwu, Gemini Official, and custom Gemini providers without changing code
  • Environment variable configuration: All provider settings controlled via environment variables
  • Flexible output: Save images to custom directories with custom filenames
  • Multiple aspect ratios: Support for 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9
  • Resolution control: 1K, 2K, 4K resolution options (default: 2K)
  • Error handling: Comprehensive error messages with HTTP status codes and response details
  • Timeout support: Configurable request timeout (default: 60s)

Supported MCP Clients

This MCP server works with:

  • Claude Desktop
  • Claude Code CLI
  • OpenCode
  • Codex
  • Any MCP-compatible client

Installation

Option 1: NPX (Recommended - No installation required)

npx -y @genoooool/mcp-image-generator

Option 2: Global Install

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

Option 3: Local Install

# Clone or download the repository
cd /path/to/project

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Environment Variables

Variable Required Description Default
IMAGE_PROVIDER Yes Provider type: yunwu, gemini_official, or custom_gemini -
IMAGE_BASE_URL Depends on provider Override default base URL Provider-specific
IMAGE_AUTH_TYPE No Auth type: bearer or apikey Provider-specific
IMAGE_TOKEN Yes for bearer auth Bearer token for authentication -
IMAGE_API_KEY Yes for apikey auth API key for authentication -
IMAGE_OUT_DIR No Default output directory for images ./output
IMAGE_REQUEST_TIMEOUT No Request timeout in milliseconds 60000

How to Switch Provider

1. Using Yunwu Provider

Set the following environment variables:

export IMAGE_PROVIDER=yunwu
export IMAGE_TOKEN=your_yunwu_token
export IMAGE_BASE_URL=https://yunwu.ai  # Optional, this is the default
export IMAGE_OUT_DIR=./images  # Optional

2. Using Gemini Official Provider

Set the following environment variables:

export IMAGE_PROVIDER=gemini_official
export IMAGE_API_KEY=your_gemini_api_key
export IMAGE_BASE_URL=https://generativelanguage.googleapis.com  # Optional, this is the default
export IMAGE_OUT_DIR=./images  # Optional

Note: Gemini Official API key authentication uses query parameter ?key= for REST API requests to generateContent endpoints.

3. Using Custom Gemini Provider

Set the following environment variables:

export IMAGE_PROVIDER=custom_gemini
export IMAGE_BASE_URL=https://your-custom-provider.com  # Required
export IMAGE_API_KEY=your_api_key  # Or use IMAGE_TOKEN with IMAGE_AUTH_TYPE=bearer
export IMAGE_AUTH_TYPE=apikey  # Optional: 'bearer' or 'apikey'
export IMAGE_OUT_DIR=./images  # Optional

MCP Client Configuration

Claude Desktop

Configuration File Location

Claude Desktop loads MCP configuration from:

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

Configuration Format

Add the MCP server to your configuration file:

{
  "mcpServers": {
    "image-generator-yunwu": {
      "command": "npx",
      "args": ["-y", "@genoooool/mcp-image-generator"],
      "env": {
        "IMAGE_PROVIDER": "yunwu",
        "IMAGE_TOKEN": "your_yunwu_token",
        "IMAGE_OUT_DIR": "./images"
      }
    },
    "image-generator-gemini": {
      "command": "npx",
      "args": ["-y", "@genoooool/mcp-image-generator"],
      "env": {
        "IMAGE_PROVIDER": "gemini_official",
        "IMAGE_API_KEY": "your_gemini_api_key",
        "IMAGE_OUT_DIR": "./images"
      }
    },
    "image-generator-custom": {
      "command": "npx",
      "args": ["-y", "@genoooool/mcp-image-generator"],
      "env": {
        "IMAGE_PROVIDER": "custom_gemini",
        "IMAGE_BASE_URL": "https://your-custom-provider.com",
        "IMAGE_API_KEY": "your_api_key",
        "IMAGE_AUTH_TYPE": "apikey",
        "IMAGE_OUT_DIR": "./images"
      }
    }
  }
}

Using Global Installation

If you installed globally:

{
  "mcpServers": {
    "image-generator": {
      "command": "mcp-image-generator",
      "env": {
        "IMAGE_PROVIDER": "yunwu",
        "IMAGE_TOKEN": "your_token"
      }
    }
  }
}

Using Local Installation

If you cloned the repository:

Windows:

{
  "mcpServers": {
    "image-generator": {
      "command": "node",
      "args": ["C:\\path\\to\\project\\dist\\index.js"],
      "env": {
        "IMAGE_PROVIDER": "yunwu",
        "IMAGE_TOKEN": "your_token"
      }
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "image-generator": {
      "command": "node",
      "args": ["/path/to/project/dist/index.js"],
      "env": {
        "IMAGE_PROVIDER": "yunwu",
        "IMAGE_TOKEN": "your_token"
      }
    }
  }
}

Claude Code CLI

Configuration File Location

Claude Code CLI loads MCP configuration from:

  • Windows: %USERPROFILE%\.claude\config.json
  • macOS/Linux: ~/.claude/config.json

Configuration Format

Add the MCP server to your configuration file:

{
  "mcpServers": {
    "image-generator-yunwu": {
      "command": "npx",
      "args": ["-y", "@genoooool/mcp-image-generator"],
      "env": {
        "IMAGE_PROVIDER": "yunwu",
        "IMAGE_TOKEN": "your_yunwu_token",
        "IMAGE_OUT_DIR": "./images"
      }
    },
    "image-generator-gemini": {
      "command": "npx",
      "args": ["-y", "@genoooool/mcp-image-generator"],
      "env": {
        "IMAGE_PROVIDER": "gemini_official",
        "IMAGE_API_KEY": "your_gemini_api_key",
        "IMAGE_OUT_DIR": "./images"
      }
    },
    "image-generator-custom": {
      "command": "npx",
      "args": ["-y", "@genoooool/mcp-image-generator"],
      "env": {
        "IMAGE_PROVIDER": "custom_gemini",
        "IMAGE_BASE_URL": "https://your-custom-provider.com",
        "IMAGE_API_KEY": "your_api_key",
        "IMAGE_AUTH_TYPE": "apikey",
        "IMAGE_OUT_DIR": "./images"
      }
    }
  }
}

Using Global Installation

If you installed globally:

{
  "mcpServers": {
    "image-generator": {
      "command": "mcp-image-generator",
      "env": {
        "IMAGE_PROVIDER": "yunwu",
        "IMAGE_TOKEN": "your_token"
      }
    }
  }
}

Using Local Installation

If you cloned the repository:

Windows:

{
  "mcpServers": {
    "image-generator": {
      "command": "node",
      "args": ["C:\\path\\to\\project\\dist\\index.js"],
      "env": {
        "IMAGE_PROVIDER": "yunwu",
        "IMAGE_TOKEN": "your_token"
      }
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "image-generator": {
      "command": "node",
      "args": ["/path/to/project/dist/index.js"],
      "env": {
        "IMAGE_PROVIDER": "yunwu",
        "IMAGE_TOKEN": "your_token"
      }
    }
  }
}

OpenCode

Configuration File Location

OpenCode loads MCP configuration from the following locations (in order of precedence):

  1. Global config: ~/.config/opencode/opencode.json
  2. Custom config: OPENCODE_CONFIG environment variable
  3. Project config: opencode.json in project root

Configuration Format

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "image-generator-yunwu": {
      "type": "local",
      "command": ["npx", "-y", "@genoooool/mcp-image-generator"],
      "enabled": true,
      "environment": {
        "IMAGE_PROVIDER": "yunwu",
        "IMAGE_TOKEN": "your_yunwu_token",
        "IMAGE_OUT_DIR": "./images"
      }
    },
    "image-generator-gemini": {
      "type": "local",
      "command": ["npx", "-y", "@genoooool/mcp-image-generator"],
      "enabled": true,
      "environment": {
        "IMAGE_PROVIDER": "gemini_official",
        "IMAGE_API_KEY": "your_gemini_api_key",
        "IMAGE_OUT_DIR": "./images"
      }
    }
  }
}

Codex

Configuration File Location

Codex loads MCP configuration from the following locations:

  1. Global config: ~/.config/codex/config.toml
  2. Project config: codex.toml in project root

Configuration Format

[mcp_servers.image_yunwu]
command = "npx"
args = ["-y", "@genoooool/mcp-image-generator"]

[mcp_servers.image_yunwu.env]
IMAGE_PROVIDER = "yunwu"
IMAGE_TOKEN = "your_token"
IMAGE_OUT_DIR = "./images"

[mcp_servers.image_gemini]
command = "npx"
args = ["-y", "@genoooool/mcp-image-generator"]

[mcp_servers.image_gemini.env]
IMAGE_PROVIDER = "gemini_official"
IMAGE_API_KEY = "your_gemini_api_key"
IMAGE_OUT_DIR = "./images"

[mcp_servers.image_custom]
command = "npx"
args = ["-y", "@genoooool/mcp-image-generator"]

[mcp_servers.image_custom.env]
IMAGE_PROVIDER = "custom_gemini"
IMAGE_BASE_URL = "https://your-custom-provider.com"
IMAGE_API_KEY = "your_api_key"
IMAGE_AUTH_TYPE = "apikey"
IMAGE_OUT_DIR = "./images"

Tool Usage

generate_image

Generate an image using AI models.

Parameters

Parameter Type Required Default Description
model string No gemini-3-pro-image-preview Model to use for generation
prompt string Yes - The prompt for image generation
aspect_ratio string No 1:1 Aspect ratio: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9
image_size string No 2K Resolution: 1K, 2K, 4K
out_dir string No ./output Directory to save the image
filename string No timestamp.png Custom filename

Return Value

{
  "url": "string",
  "file_path": "string | null",
  "provider": "string"
}

Note: For Yunwu provider, if the response does not include a URL field, only file_path will be returned and url will be empty.

Example Usage

Example 1: Generate a simple image

Input:

{
  "prompt": "A beautiful sunset over the ocean",
  "aspect_ratio": "16:9",
  "image_size": "2K"
}

Output:

{
  "url": "",
  "file_path": "./images/20260111_034500.png",
  "provider": "yunwu"
}

Example 2: Generate with custom filename

Input:

{
  "prompt": "A futuristic cityscape at night",
  "model": "gemini-3-pro-image-preview",
  "aspect_ratio": "1:1",
  "out_dir": "./my_images",
  "filename": "cityscape.png"
}

Output:

{
  "url": "",
  "file_path": "./my_images/cityscape.png",
  "provider": "gemini_official"
}

Example 3: Generate with direct URL (if supported)

Input:

{
  "prompt": "A peaceful mountain landscape",
  "aspect_ratio": "4:3",
  "image_size": "1K"
}

Output:

{
  "url": "https://cdn.example.com/images/abc123.png",
  "file_path": null,
  "provider": "yunwu"
}

Development

Build

npm run build

Development Mode (with auto-reload)

npm run dev

Manual Testing

You can test the server manually by running:

IMAGE_PROVIDER=yunwu \
IMAGE_TOKEN=your_token \
node dist/index.js

Then send JSON-RPC messages via stdin.

Provider Details

Yunwu Provider

  • Endpoint: POST https://yunwu.ai/v1beta/models/{model}:generateContent
  • Authentication: Bearer token via Authorization: Bearer {token} header
  • Response Handling:
    • If response contains fileData.uri, returns the URL in url field
    • If response contains inlineData.data, decodes base64 and saves to local file
    • If no URL is available, url will be empty and only file_path is guaranteed

Gemini Official Provider

  • Endpoint: POST https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={api_key}
  • Authentication: API key via query parameter ?key= in the URL
  • Response Handling: Same as Yunwu provider

Custom Gemini Provider

  • Endpoint: Configurable via IMAGE_BASE_URL
  • Authentication: Supports both bearer token and API key based on IMAGE_AUTH_TYPE
    • bearer: Authorization: Bearer {token} header
    • apikey: ?key={api_key} query parameter

Error Handling

The server returns detailed error messages when issues occur:

  • HTTP errors: Includes HTTP status code and response body
  • Validation errors: Includes field names and validation messages
  • Configuration errors: Clearly indicates missing required environment variables

Example error response:

Yunwu API error (401): {"error": "Invalid token"}

Troubleshooting

"IMAGE_PROVIDER environment variable is required"

Make sure you set the IMAGE_PROVIDER environment variable.

"IMAGE_TOKEN is required when IMAGE_AUTH_TYPE=bearer"

You're using bearer auth type but didn't provide a token. Either:

  • Set IMAGE_TOKEN environment variable
  • Change to apikey auth type and set IMAGE_API_KEY

"Unable to extract image from response"

The API response format may have changed. Check the provider's API documentation.

Timeout errors

Increase the timeout by setting IMAGE_REQUEST_TIMEOUT:

export IMAGE_REQUEST_TIMEOUT=120000  # 120 seconds

Claude Code doesn't show the MCP server

  1. Make sure you've restarted Claude Code after editing the config file
  2. Check that the configuration file path is correct for your OS
  3. Verify the command works in your terminal (e.g., run npx -y @genoooool/mcp-image-generator)
  4. Check Claude Code logs for error messages

License

MIT

Author

genoooool

Links

About

An MCP server for AI image generation with multi-provider support.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages