Genai MCP

GenAI MCP Server

This project implements a Model Context Protocol (MCP) server for image generation and image editing using Google Gemini, Tongyi Wanxiang, plus optional automatic upload of generated images to S3‑compatible object storage (AWS S3, Aliyun OSS, etc.).

The server exposes a streamable HTTP MCP endpoint and provides tools for Gemini, Wan, and APIMart.

Provider matrix

1. Prerequisites

• Go 1.21+ (recommended)
• A valid Gemini (or provider) API key
• Optional: S3 / OSS bucket for storing images

2. Configuration (.env)

Copy env.example to .env, then fill in real values.

GenAI configuration

# GenAI provider:
# - gemini: Google Gemini / compatible backend
# - wan:    Ali Bailian Tongyi Wanxiang image APIs
# - apimart: APIMart (Gemini-wrapped async image APIs)
GENAI_PROVIDER=gemini

# Shared GenAI endpoint / key for all providers
GENAI_BASE_URL=https://generativelanguage.googleapis.com
GENAI_API_KEY=your_api_key_here

# Model names:
# - When GENAI_PROVIDER=gemini: Gemini model names, e.g. gemini-3-pro-image-preview
# - When GENAI_PROVIDER=wan:    Wanxiang model names, e.g. wan2.5-t2i-preview / wan2.5-i2i-preview
# - When GENAI_PROVIDER=apimart: Gemini image model name, e.g. gemini-3-pro-image-preview
GENAI_GEN_MODEL_NAME=gemini-3-pro-image-preview
GENAI_EDIT_MODEL_NAME=gemini-3-pro-image-preview

# Request timeout in seconds for each GenAI call (generate / edit)
GENAI_TIMEOUT_SECONDS=120

# Image output format:
# - base64: return image as data URI (base64 encoded)
# - url:    upload image to OSS and return plain URL
GENAI_IMAGE_FORMAT=base64

HTTP server

SERVER_ADDRESS=0.0.0.0
SERVER_PORT=8080

MCP endpoint:

http://SERVER_ADDRESS:SERVER_PORT/mcp

OSS / S3 configuration (optional, required when GENAI_IMAGE_FORMAT=url)

# For AWS S3: leave OSS_ENDPOINT empty or set to s3.amazonaws.com
# For Aliyun OSS: set to oss-cn-hangzhou.aliyuncs.com or your region
# For Tencent COS: set to cos.ap-guangzhou.myqcloud.com
# For MinIO: set to your MinIO endpoint
OSS_ENDPOINT=
OSS_REGION=us-east-1
OSS_ACCESS_KEY=your_access_key_here
OSS_SECRET_KEY=your_secret_key_here
OSS_BUCKET=your_bucket_name

When GENAI_IMAGE_FORMAT=url:

• For Aliyun OSS: ensure OSS_ENDPOINT like oss-cn-beijing.aliyuncs.com and bucket policy allows expected read access.

3. Running the MCP Server

You can run the MCP server in two ways:

1. Clone & build from source

   • Clone this repo and enter the project root

   • Copy env.example to .env and fill in your configuration

   • Run:

     go build .
     ./genai-mcp
     

2. Download release binary

   • Download the appropriate binary from the Releases page

   • Place it in a directory of your choice

   • Copy env.example (from repo or release asset) to .env and update configuration

   • Run (binary name may vary by platform):

     ./genai-mcp
     

Default MCP HTTP endpoint:

http://127.0.0.1:8080/mcp

Connect from any MCP‑compatible client supporting streamable HTTP transport.

4. MCP Tools

Gemini tools (internal/tools/gemini.go)

• gemini_generate_image

  • Input: prompt (string, required)
  • Output: base64 data URI or URL (optional OSS upload)

• gemini_edit_image

  • Input: prompt (required), image_urls (required, JSON array)
  • Output: base64 data URI or URL

When GENAI_IMAGE_FORMAT=url, images are downloaded/decoded then uploaded to OSS/S3 under images/yyyy-MM-dd/{uuid_timestamp_random}.ext.

Wan tools (internal/tools/wan.go)

• wan_create_generate_image_task
• wan_query_generate_image_task
• wan_create_edit_image_task
• wan_query_edit_image_task

Wan is async; create a task then poll for completion.

APIMart tools (internal/tools/apimart.go)

• apimart_create_generate_image_task
• apimart_query_generate_image_task
• apimart_create_edit_image_task
• apimart_query_edit_image_task

APIMart is async; tools return the final image (URL or base64) once the task is completed.

5. Contact

• WeChat: Scan the QR code below to add as a friend

  

• Discord: Join the community

Star History