Assets Generation MCP Server

English | 简体中文

An MCP server for AI image generation with dual-provider support for OpenAI-compatible models and Google Gemini. It returns standard MCP ImageContent blocks.

Features

• Automatically selects the provider from the model name
• When both OpenAI and Gemini are configured, provider selection is still based on the requested model; if no model is provided, DEFAULT_MODEL is used
• Returns images as MCP-standard ImageContent ({ type: "image", data, mimeType })
• Supports three transports: stdio (default), SSE, and HTTP
• Supports custom API proxy endpoints (OPENAI_BASE_URL / GEMINI_BASE_URL)
• Automatically loads .env, and also supports CLI arguments for MCP clients that cannot pass env
• Providers without valid API keys are disabled automatically without affecting the other provider

Quick Start

npm install
npm run build
cp .env.example .env

Environment Variables

Variable	Required	Default	Description
GEMINI_API_KEY	One provider required	-	Google Gemini API key
OPENAI_API_KEY	One provider required	-	OpenAI-compatible API key
DEFAULT_MODEL	No	gemini-2.5-flash-image	Default model when the tool call does not provide model
GEMINI_BASE_URL	No	-	Gemini API proxy endpoint
OPENAI_BASE_URL	No	-	OpenAI-compatible API proxy endpoint
OPENAI_IMAGE_MODEL	No	gpt-image-2	OpenAI-compatible image model used in integration tests
MCP_TRANSPORT	No	stdio	Transport mode: stdio / sse / http
MCP_STDIO_LOGS	No	false	Enable startup/runtime logs in stdio mode (set true to re-enable for debugging)
MCP_HOST	No	localhost	Host for SSE/HTTP mode
MCP_PORT	No	3000	Port for SSE/HTTP mode

Configure at least one of GEMINI_API_KEY or OPENAI_API_KEY.

Placeholder values in .env such as your-gemini-api-key are ignored automatically.

Configuration precedence is: CLI arguments > process environment variables > .env in the current working directory > built-in defaults.

Tool: generate_image

Parameter	Required	Default	Description
prompt	Yes	-	Detailed image description
model	No	DEFAULT_MODEL	Model name — see supported models below
size	No	auto / 1024x1024	Image dimensions for OpenAI-compatible models
quality	No	standard	high/medium/low/standard (gpt-image-*) or hd/standard (dall-e-3)
n	No	1	Number of images (gpt-image-*: 1–10; dall-e-3: 1; Gemini: 1)
aspect_ratio	No	1:1	Gemini-only: 1:1 3:4 4:3 9:16 16:9
response_format	No	auto	url / base64 / auto — see Response Format below
timeout	No	120	Max wait time in seconds. Increase for slow proxies or high-quality models

Supported model families:

• OpenAI / OpenAI-compatible: gpt-image-2, gpt-image-1, dall-e-3, dall-e-2, doubao-*, volcengine/doubao-*
• Gemini: gemini-2.5-flash-image, gemini-2.0-flash-exp, imagen-3.0-generate-001

Response Format

The response_format parameter controls how image URLs and file paths are returned alongside the base64 ImageContent blocks:

Value	Behavior
auto (default)	Always returns a local file path in the response text (Saved to: /tmp/abc123.png) alongside the base64 ImageContent block. Images are saved to os.tmpdir() with a random filename. This mode is the most compatible and ensures the image is always accessible regardless of the provider's default response format.
base64	Returns ImageContent blocks only (forces b64_json for OpenAI).
url	Always returns a file path or URL in the response text: <br>• If the API returns a url → Image URL: https://... <br>• If the API returns only base64 → the image is saved to os.tmpdir() with a random filename → Saved to: /tmp/abc123.png

Security: files saved to the temp directory use crypto.randomBytes(16) for filenames with wx (exclusive-create) and 0o600 (owner-only) flags — no path-traversal risk, no file-overwrite collisions.

Usage

Claude Desktop / Kiro (stdio mode)

{
  "mcpServers": {
    "assets-gen": {
      "command": "node",
      "args": ["/path/to/assets-gen-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "GEMINI_BASE_URL": "https://your-proxy.com"
      }
    }
  }
}

If your MCP client cannot pass env, use CLI arguments instead:

{
  "mcpServers": {
    "assets-gen": {
      "command": "npx",
      "args": [
        "-y",
        "@ayaka209/assets-gen-mcp",
        "--openai-api-key",
        "your-key",
        "--openai-base-url",
        "https://your-proxy.com/gptapi",
        "--default-model",
        "gpt-image-2"
      ]
    }
  }
}

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

MCP SDK Client

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["dist/index.js"],
  env: { GEMINI_API_KEY: "your-key" },
});

const client = new Client({ name: "my-app", version: "1.0.0" }, { capabilities: {} });
await client.connect(transport);

const result = await client.callTool({
  name: "generate_image",
  arguments: { prompt: "A cat in space" },
});

// result.content -> [{ type: "image", data: "<base64>", mimeType: "image/png" }]

Provider Selection Rules

1. If model is provided, the provider is chosen from the model prefix
2. If model is omitted, DEFAULT_MODEL is used
3. gpt-image-* / dall-e-* / doubao-* / volcengine/doubao-* go to the OpenAI-compatible path
4. gemini-* / imagen-* go to the Gemini path

SSE / HTTP Mode

MCP_TRANSPORT=sse MCP_PORT=3000 node dist/index.js

Endpoints:

• GET /sse - SSE connection
• POST /message?sessionId=xxx - Send messages
• GET / - Health check

OpenAI-Compatible Proxy Testing

Run the full integration tests:

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint
OPENAI_IMAGE_MODEL=gpt-image-2
npm run test:integration

For a single end-to-end smoke test:

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint
OPENAI_IMAGE_MODEL=gpt-image-2
npm run test:openai-proxy

This script verifies:

1. A direct images.generate call against OPENAI_BASE_URL
2. A stdio MCP round-trip through this repository's generate_image tool

To inspect which OpenAI-compatible models your endpoint exposes:

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint
npm run models:openai

If your MCP client cannot pass env, you can launch it directly with CLI arguments:

npx -y @ayaka209/assets-gen-mcp --openai-api-key sk-... --openai-base-url https://your-openai-compatible-endpoint --default-model gpt-image-2

Show all supported CLI options:

npx -y @ayaka209/assets-gen-mcp --help

Development

npm run build             # Build
npm run watch             # Watch TypeScript
npm test                  # Unit tests
npm run test:integration  # Integration tests (requires API keys)
npm run test:openai-proxy # One-command OpenAI-compatible smoke test
npm run models:openai     # List OpenAI-compatible models visible to the endpoint
npm run models            # List available Gemini models

Tech Stack

• @modelcontextprotocol/sdk - MCP server/client SDK
• @google/genai - Google Gemini SDK
• openai - OpenAI SDK

License

MIT