Explain Image MCP Server

A zero-dependency MCP (Model Context Protocol) server that lets any AI agent — including text-only models — "see" images.

The agent passes an image (local path, URL, or data URL) plus a prompt to the describe_image tool. The server forwards both to a Gemini vision model through the OpenAI-compatible REST endpoint and returns the model's text interpretation. Because the agent supplies the prompt, it controls exactly what the model returns: a description, OCR of visible text, an object list, structured JSON, and so on.

No external libraries are used — the MCP JSON-RPC protocol is implemented by hand over stdio, and the Gemini request is a plain fetch().

AI agent ── describe_image(image, prompt) ──► MCP server (stdio, JSON-RPC 2.0)
                                                  │
                                                  ▼
                              POST /chat/completions  (OpenAI-compatible)
                                                  │
                                                  ▼
                                            Gemini vision model

Requirements

• Node.js >= 18.17 (global fetch required)
• A Gemini API key

Configuration

Env var	Default	Description
GEMINI_API_KEY	(required)	Google AI Studio API key
GEMINI_MODEL	gemini-2.5-flash	Default model id; override per call with the model argument
GEMINI_BASE_URL	https://generativelanguage.googleapis.com/v1beta/openai	OpenAI-compatible base URL (swap to add another provider later)

Install with an MCP client

san:

san mcp add -e GEMINI_API_KEY=your-key explain-image -- node /path/to/explain-image-mcp-server/src/index.js

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "explain-image": {
      "command": "node",
      "args": ["/path/to/explain-image-mcp-server/src/index.js"],
      "env": { "GEMINI_API_KEY": "your-key" }
    }
  }
}

Tools

describe_image

Analyze one or more images with a Gemini vision model. The agent supplies the prompt.

Argument	Type	Required	Description
image	string | string[]	yes	Local file path, http(s) URL, data: URL, or an array of these
prompt	string	no	What the model should return. Defaults to a detailed description
model	string	no	Gemini model id, overrides GEMINI_MODEL
max_tokens	integer	no	Maximum response length

Example agent call:

describe_image(
  image: "/screenshots/bug.png",
  prompt: "Describe this UI bug precisely: what is shown, and what looks wrong?"
)

list_models

List the model ids available on the configured OpenAI-compatible endpoint.

Default model & cost

The default is gemini-2.5-flash — a cost-efficient GA Flash model with image input (Google pricing, July 2026): $0.30 / 1M input tokens, $2.50 / 1M output tokens (vs $1.50 / $7.50 for gemini-3.6-flash). For 2.5 Flash/Flash-Lite models the server sends reasoning_effort: "none", disabling thinking so no output tokens are spent on reasoning. Set GEMINI_MODEL (or pass model per call) to use a different model, e.g. gemini-3.6-flash for higher quality at a higher price.

Development

npm test   # end-to-end smoke test (protocol handshake + request formatting, no real key needed)

The smoke test runs the full MCP handshake against a fake OpenAI-compatible upstream and validates the request shape (auth header, message body, base64 data URL) plus error paths.

Security note

The API key is stored in plaintext wherever the MCP client saves env vars. Keep it out of version control — .san/ is git-ignored in this repo for that reason.