Gemini Image

This MCP server runs a Python-based Gemini image toolbox inside a Docker container. It exposes image editing and image analysis capabilities over Streamable HTTP, enabling you to send requests to transform or inspect images using Google Gemini APIs through a simple network interface.

How to use

You run the container, then connect with any MCP client to access two tools: image_edit and image_analyze. The server listens on port 8000 inside the container and exposes the MCP endpoint at /mcp. You can start by building the image, launching the container, and then querying the available tools from your MCP client, followed by making edit or analyze requests.

How to install

Prerequisites you need before starting:

• Docker installed on your host
• A Google Gemini API key
• Python 3.11+ and uv (for running tests)

Build the container image from source using the following command:

docker build -t vocabai/gemini-image-mcp .

Run the container with your Gemini API key. The server will be available at localhost:8000/mcp.

docker run --rm --network host -e GEMINI_API_KEY=your_key_here vocabai/gemini-image-mcp

Starting and connecting from an MCP client

Once the container is running, connect from any MCP client to the endpoint and list the available tools. You will interact with the two tools: image_edit and image_analyze.

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async with streamable_http_client("http://localhost:8000/mcp") as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        print([t.name for t in tools.tools])

Security and keys

Secure usage requires you to provide a valid Google Gemini API key. Do not expose the API key in client code or logs. If you run in a shared environment, consider limiting access to the MCP endpoint and rotating keys as needed.

Notes

The server relies on the Google Gemini API through the google-genai SDK and uses FastMCP with Streamable HTTP transport. Enable Server-Sent Events support if you plan to use SSE-heavy clients; using Docker’s host networking helps ensure SSE compatibility.

Available tools

image_edit

Edits an existing image based on a text prompt. Accepts a base64-encoded image, MIME type, and prompt. Returns the edited image as ImageContent.

image_analyze

Answers a question about an image. Accepts a base64-encoded image, MIME type, and a question. Returns a text answer.