RelayOne Image MCP

This is the MCP integration package for RelayOne Image, supporting both the Image2 and Gemini Banana image generation routes. Each user only needs to configure a single RelayOne API Key.

Two Image Generation Providers

Banana also supports gemini-3-pro-image. Its imageSize uses 512, 1K, 2K, 4K resolution tiers, and aspectRatio controls the aspect ratio; it does not use Image2's fixed widthxheight dimension protocol.

Related MCP server: Gemini Image Generation MCP Server

Supported Models

Image2

Gemini Banana

gemini-3-pro-image-preview is normalized to gemini-3-pro-image; it is an alias rather than a third independent model. Both Banana models use the same generateContent endpoint for text-to-image and image-to-image generation; whether reference_images is included determines whether it is text-to-image or image-to-image.

After selecting a Provider, MCP automatically selects the protocol:

• When image2 has no reference_images, it calls the /v1/images/generations JSON; when reference images are present, it calls /v1/images/edits as multipart and uploads the reference images using image[].

• banana always calls /v1beta/models/{model}:generateContent; reference images are converted to contents[].parts[].inlineData, not multipart, and not OpenAI Images JSON.

What the Site Needs to Fill In

1. config/providers.json already configures the RelayOne address, models, requires the corresponding group to be enabled. Request path, and Images path; modify it if you need to switch sites.

2. Each agent copies .env.example to .env and only fills in SITE_IMAGE_API_KEY; do not write the key into tool parameters.

3. If a proxy is needed, additionally set SITE_IMAGE_PROXY_URL on the machine running MCP. This is optional.

4. If the site does not use Bearer authentication or is not compatible with the OpenAI-compatible request format, modify the adaptation logic in callProvider and the request schema in src/index.ts.

5. Run npm install and npm run build, then register dist/index.js with the MCP client.

.env is automatically read when MCP starts, so the agent does not need to modify the startup command.

MCP Registration Example

Replace PACKAGE_DIRECTORY in mcp-server.example.json with the current package directory, then register it according to the configuration format of the MCP client you are using. .env and dist/index.js must be at the same directory level as this folder.

Description of Error Return Value

• list_image_providers: Displays locally configured channels, without displaying keys.

• list_remote_image_models: Reads the real-time list of available models, without generating images.

• get_image_capabilities: Views the parameter capabilities filled in by the site administrator.

• get_image_usage: Reads the optional usage API, without generating images.

• Web Images API (Jina AI Reader).

• generate_image: Must provide a local absolute path save_directory before calling. The tool preserves the complete raw response JSON (via the Image API) and saves the image files to the specified directory, while also returning MCP image content.

Custom Parameters for Each Call

Pass standard fields directly, and put site-specific fields in custom_parameters. For example:

{
  "prompt": "一座雨夜城市",
  "size": "1024x1024",
  "custom_parameters": {
    "steps": 30,
    "guidance_scale": 7,
    "seed": 12345,
    "negative_prompt": "模糊、低清晰度"
  }
}

custom_parameters will be merged into the current request JSON; provider, model, prompt, custom_parameters, and any already-passed standard fields cannot be overridden.

Custom Parameters

• The actual key should only go into the startup environment, not into providers.json, code, logs, or MCP tool parameters.

• save_directory must be explicitly selected by the user each time before generating an image; MCP does not decide the save location on its own.

• A .response.json file containing the raw response, and image files named by sequence number, will be generated in the save directory.

• URL image downloads only allow HTTP(S) and are limited to 25 MB; if the download fails, the original URL remains in .response.json.

• Authorization headers will not be printed in any request or response.

• Arbitrary pass-through of parameters is not predefined; site administrators should add allowlisted fields individually according to their own API.

Codex Registration

In Codex, register node dist/index.js in the MCP configuration, and pass the RelayOne key via the configured environment variables. Do not put real values into the example files or send them to third parties.

Project address: https://github.com/linshiqiyyds/relayone-image-mcp

Image Generation Call Examples

When calling generate_image, a save directory must be selected first. For example:

{
  "prompt": "一只橘猫坐在窗边，电影感，自然光",
  "size": "1024x1024",
  "response_format": "b64_json",
  "save_directory": "D:\\RelayOne-MCP\\generated"
}

If you choose response_format: "url", MCP will download the image from the URL; if you choose b64_json, MCP will decode the Base64. Both raw fields are preserved as-is in the .response.json file.

Image2 Examples

{
  "provider": "image2",
  "model": "gpt-image-2",
  "prompt": "一张产品摄影图",
  "size": "2048x1152",
  "response_format": "url",
  "save_directory": "D:\\RelayOne-MCP\\generated"
}

For Image2 image-to-image in the image conversion, you only need to add the local reference image path, and MCP will automatically switch to /v1/images/edits:

{
  "provider": "image2",
  "model": "gpt-image-2",
  "prompt": "保留主体，把背景改成夜晚城市",
  "reference_images": ["D:\\References\\product.png"],
  "size": "2048x1152",
  "save_directory": "D:\\RelayOne-MCP\\generated"
}

Banana Examples

{
  "provider": "banana",
  "model": "gemini-3.1-flash-image",
  "prompt": "把产品放在夜晚城市街道中",
  "aspectRatio": "16:9",
  "imageSize": "2K",
  "reference_images": [
    "D:\\References\\product.png"
  ],
  "save_directory": "D:\\RelayOne-MCP\\generated"
}

For Banana, reference images are read as plain Base64, placed into contents[].parts[].inlineData according to the native Gemini protocol. Up to 14 images, each up to 20 MB, supporting PNG, JPEG, and WebP. Banana models do not use gpt-image-2, nor do they support Image2 fixed pixel resolution.