gemini-vision-mcp-safe

English｜简体中文

A minimal, privacy-conscious MCP server that lets an MCP client (Claude Code, Claude Desktop, etc.) ask Google Gemini to look at an image — local file or URL — and return a description, text extraction, comparison, and so on.

The "safe" in the name is a design goal:

• Two-step handshake before any image leaves the machine. The first call returns a Chinese confirmation prompt; the second call (with confirm_send_to_gemini=true) is the only one that actually talks to Gemini. This stops a model from silently uploading user files to Google.

• SSRF defenses for URL inputs: protocol allowlist, manual redirect handling, per-hop DNS check against private/loopback ranges, HTTPS→HTTP downgrade refused.

• Magic-byte sniffing instead of trusting file extensions or Content-Type.

• Configurable size cap with both Content-Length pre-check and a hard streaming limit; remote bodies stream to a temp file that is removed in finally.

• Proxy aware via HTTPS_PROXY / HTTP_PROXY. Useful where Google APIs are not directly reachable (e.g. mainland China through clash/mihomo). The proxy URL is redacted in logs.

• API key in .env, not in the MCP config. The repo's .gitignore excludes .env so the key never ends up in git.

Result text and error messages are in Chinese.

Tools

analyze_image_with_gemini

Send one local image or one HTTP/HTTPS image URL to Gemini.

analyze_images_batch

Send 2–5 images in a single Gemini call (good for "compare these screenshots" or multi-page documents).

If one image fails to load, the error message tells you which one (第 N 张: …).

Related MCP server: nanobanana-mcp

Install

git clone https://github.com/nianshou555qiansui/gemini-vision-mcp-safe.git
cd gemini-vision-mcp-safe
npm install
npm run build
cp .env.example .env       # then edit .env, paste your Gemini API key

Get a key at https://aistudio.google.com/apikey.

Wire it up

Claude Code

~/.claude.json (or claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "gemini-vision-safe": {
      "type": "stdio",
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/gemini-vision-mcp-safe/.env",
        "/absolute/path/to/gemini-vision-mcp-safe/dist/index.js"
      ],
      "env": {
        "HTTPS_PROXY": "http://127.0.0.1:7890",
        "HTTP_PROXY": "http://127.0.0.1:7890"
      }
    }
  }
}

--env-file requires Node ≥ 20.6. The env block in MCP config is for non-secret settings (proxy address); the API key lives in .env so it never ends up in version control or shared configs.

On Windows where the launcher needs a shell, use cmd /c node … instead of node ….

Configuration

.env keys (see .env.example):

Privacy notes

• A local file path stays local; only the bytes of the file you confirm travel to Gemini.

• A URL is fetched from your machine first, then forwarded to Gemini — the original host sees your IP (or your proxy's), but never sees Google. Conversely Google never sees the original host.

• The repo never contains an API key. Verify before committing: git ls-files | grep -F .env should print nothing.

Caveats

• DNS rebinding / TOCTOU is not mitigated: the SSRF check uses the OS resolver, but the actual TCP connect resolves again. Acceptable for local use; not safe to expose this MCP as a public service.

• The OS resolver does not go through HTTPS_PROXY. If your local DNS is unreliable, prefer URLs whose hostnames you've already pre-resolved or run a trusted DNS upstream.

• Per-region Gemini availability is Google's decision. The error mapper will tell you when it sees 403 / 429 / 503.

License

MIT — see LICENSE.