gemini-3-pro-mcp-streamable-http-mcp

A Docker-based deployment that wraps the RLabs-Inc/gemini-mcp stdio MCP server with supergateway to expose it over Streamable HTTP. Includes a Python test suite that validates the full image-edit workflow end-to-end.

Architecture

Client (MCP SDK)
    │
    │  Streamable HTTP  (POST/GET http://host:8000/mcp)
    ▼
┌────────────────────────────────────────────┐
│  Docker Container                          │
│                                            │
│  supergateway                              │
│    --stdio "gemini-mcp"                    │
│    --outputTransport streamableHttp        │
│    --port 8000                             │
│         │                                  │
│         │ stdio (stdin/stdout)             │
│         ▼                                  │
│  @rlabs-inc/gemini-mcp                     │
│    (talks to Google Gemini API)            │
└────────────────────────────────────────────┘

supergateway spawns gemini-mcp as a child process, speaks MCP over stdio with it, and re-exposes every tool over a single Streamable HTTP endpoint at /mcp.

Prerequisites

• Docker

• A Google Gemini API key

• Python 3.10+ (for running the tests)

Quick Start

Build the image

docker build -t gemini-mcp .

Run the container

docker run -e GEMINI_API_KEY=your_key_here -p 8000:8000 gemini-mcp

The MCP server is now available at http://localhost:8000/mcp.

Connect from any MCP client

Any client that supports Streamable HTTP transport can connect. For example, with the MCP Python SDK:

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_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])

File Reference

Dockerfile

FROM node:22-slim
RUN npm install -g supergateway @rlabs-inc/gemini-mcp
ENV GEMINI_API_KEY=""
EXPOSE 8000
CMD ["supergateway", "--stdio", "gemini-mcp", \
     "--outputTransport", "streamableHttp", "--port", "8000"]

Test Suite

Dependencies

Install with:

pip install -r requirements.txt

Running the tests

GEMINI_API_KEY=your_key pytest test_gemini_mcp.py -v

The test suite is fully self-contained: it builds the Docker image, starts the container, runs the tests, and tears the container down afterward.

Fixtures

Tests

test_list_tools

Connects to the MCP server and verifies that the expected image-edit tools are exposed:

• gemini-start-image-edit

• gemini-continue-image-edit

• gemini-end-image-edit

test_image_edit_workflow

End-to-end image editing round-trip:

1. Start session -- calls gemini-start-image-edit with a prompt ("a simple red circle on a white background"), asserts an ImageContent and TextContent block are returned, extracts the session ID.

2. Apply edit -- calls gemini-continue-image-edit with the session ID and an edit instruction ("change the red circle to a blue star"), asserts a new image is returned.

3. Download -- base64-decodes the image data and writes it to a temp file.

4. Validate -- opens the bytes with Pillow, calls verify() to check integrity, asserts width/height > 0 and format is PNG/JPEG/WEBP/GIF. Also validates the file written to disk.

5. Close session -- calls gemini-end-image-edit to clean up the server-side session.

Configuration constants

Environment Variables

The @rlabs-inc/gemini-mcp package also supports optional variables (GEMINI_OUTPUT_DIR, GEMINI_TOOL_PRESET, GEMINI_PRO_MODEL, etc.) which can be passed through with additional -e flags on docker run.

License

See upstream projects for license terms:

• supergateway

• gemini-mcp