OpenRouter Custom Image Generation MCP Server

This MCP Server provides tools to generate images using OpenRouter models (defaulting to google/gemini-2.5-flash-image for high performance) and integrates with LibreChat's database to retrieve images uploaded by users.

📂 Project Structure

This MCP Server is split into specialized modules for maximum maintainability:

• index.js: Main entrypoint. Sets up the Express app, SSE transports, instantiates the MCP server, and registers the tools.

• tools.js: Implementations for MCP tool handlers (get_user_images, generate_image). Includes the intelligent index-to-file_id resolution.

• files.js: File utilities. Connects to MongoDB to fetch image records and reads local file streams from disk.

• db.js: MongoDB connection pool manager.

• openrouter.js: Communicates with OpenRouter API endpoints (chat completions with image modalities and dedicated image endpoints).

Related MCP server: OpenRouter Image MCP Server

🛠️ Tools Provided

1. get_user_images

• Description: Retrieves a list of images that the user uploaded to LibreChat.

• Arguments: limit (optional - default 10).

• Return Format: A text list containing file IDs, filenames, and short index identifiers:

  Found 2 uploaded image(s):
  1. [INDEX_1] file_id: "cab88c4e-aecb-4812-9fff-6c85aede6362" — mycar.png
  2. [INDEX_2] file_id: "f6752381-3a6d-4b69-a92b-5555a9521069" — cat.png
  
  Use EITHER the file_id OR the index number (e.g., '1', '2' or 'INDEX_1', 'INDEX_2') as the reference_image_url when calling generate_image.

2. generate_image

• Description: Generates an image from a detailed text description. Can perform Image-to-Image when reference images are provided.

• Arguments:

  • prompt (required): Text description of the image to generate (translated to English if in another language).

  • reference_image_url or reference_image_urls (optional): The file_id OR index number (like "1" or "INDEX_1") of the reference image(s) from get_user_images.

  • model (optional): OpenRouter model to use (default: google/gemini-2.5-flash-image).

⚙️ Index-to-File_ID Resolution Architecture (How it Works)

Since the LLM Agent only receives the raw base64 image bytes in the chat history, it does not natively know the database file_id of the uploaded image. To prevent the model from using the Google/OpenAI temporary file-xxxx IDs (which are not in your local database), we use an intelligent, stateless index resolution mechanism:

sequenceDiagram
    actor User as User
    participant Agent as LLM Agent (Text Model)
    participant MCP as MCP Server
    participant DB as MongoDB (LibreChat)

    User->>Agent: "Edit this image of a car" (uploads car.png)
    Note over Agent: Agent sees car.png in context.
    Note over Agent: Agent reads tool schema warning against file-xxxx IDs.
    Agent->>MCP: Call get_user_images()
    MCP->>DB: Query latest images for User
    DB-->>MCP: Returns [car.png (file-abc)]
    MCP-->>Agent: "1. [INDEX_1] file_id: 'file-abc' — car.png"
    Note over Agent: Agent maps car.png to "INDEX_1"
    Agent->>MCP: Call generate_image(prompt="make it red", reference_image_url="1")
    Note over MCP: MCP intercepts index "1"
    MCP->>DB: Query latest images for User (matches same sorting)
    DB-->>MCP: Returns [car.png (file-abc)]
    Note over MCP: MCP maps index "1" to file_id "file-abc"
    MCP->>MCP: Fetches file-abc from disk and generates image via OpenRouter
    MCP-->>User: Returns edited image!

🚀 Installation & Deployment

Step 1: Configure Environment Variables (.env)

Add the following to the .env file at the root of your LibreChat repository:

OPENROUTER_KEY=your_openrouter_api_key_here

# (Optional) Image generation limits per user
IMAGE_GEN_DAILY_LIMIT=5
IMAGE_GEN_COOLDOWN_SEC=30

Step 2: Register the MCP Server in librechat.yaml

Add this to the end of librechat.yaml:

mcpSettings:
  allowedDomains:
    - 'mcp-image-gen'
  allowedAddresses:
    - 'mcp-image-gen:3013'

mcpServers:
  openrouter-imager:
    type: sse
    url: http://mcp-image-gen:3013/sse
    headers:
      x-user-id: '{{LIBRECHAT_USER_ID}}'

Step 3: Start the Services

Run the following command to build the MCP server container and run it:

docker compose up -d --build

And restart the LibreChat API service:

docker compose restart api