Skip to main content
Glama
nianshou555qiansui

gemini-vision-mcp-safe

by nianshou555qiansui
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
JavaScript
Local

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.

Parameter

Required

Description

image_source

yes

Local path (C:/path/to.png) or URL (https://…).

prompt

no

What to ask Gemini. Defaults to a Chinese "describe this image" prompt.

model

no

Override the model for this call (e.g. gemini-2.5-flash). Falls back to GEMINI_VISION_MODEL.

confirm_send_to_gemini

no

Must be true to actually send. Defaults to false.

analyze_images_batch

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

Parameter

Required

Description

image_sources

yes

Array of 2–5 paths or URLs. Mixed is fine.

prompt

no

What to ask Gemini across all images.

model

no

Same as above.

confirm_send_to_gemini

no

Same handshake.

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):

Key

Default

Notes

GEMINI_API_KEY

(required)

Your key from Google AI Studio.

GEMINI_VISION_MODEL

gemini-2.5-flash

Default model. Per-call model arg overrides this.

GEMINI_VISION_MAX_IMAGE_MB

10

Hard cap. Remote images that exceed this via Content-Length are rejected before download; the streaming reader also enforces it.

GEMINI_VISION_REQUEST_TIMEOUT_MS

20000

Per-hop URL fetch timeout.

GEMINI_VISION_GEMINI_TIMEOUT_MS

60000

SDK-level timeout for the Gemini call.

GEMINI_VISION_ALLOW_URL

true

Set false to refuse URL inputs entirely.

GEMINI_VISION_ALLOW_LOCAL_FILE

true

Set false to refuse local file inputs.

GEMINI_VISION_BLOCK_LOCAL_URLS

true

Set false to disable SSRF/private-IP blocking (not recommended).

HTTPS_PROXY / HTTP_PROXY

unset

Used by both fetch and the Gemini SDK via undici's global dispatcher.

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.

Available Tools

2 tools
analyze_images_batchA
Read-only

Batch analyze multiple images (2-5) using Google Gemini Vision.

Same privacy rules as analyze_image_with_gemini apply. Useful for comparing screenshots, before/after views, or multi-page documents.

Supported inputs: local file paths or HTTP/HTTPS image URLs (can mix).

ParametersJSON Schema
NameRequiredDescriptionDefault
image_sourcesYesArray of 2-5 image sources (local paths or URLs). Example: ['C:/a.png', 'https://example.com/b.png']
promptNoWhat to analyze across all images. Example: 'Compare these two screenshots and list differences.'
modelNoOverride the Gemini model. Defaults to env GEMINI_VISION_MODEL.
confirm_send_to_geminiNoMust be true only after the user explicitly agrees. Defaults to false.

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing non-destructive read behavior. The description adds value by specifying the underlying model (Google Gemini Vision), privacy alignment, and supported input types (local paths or URLs). It does not, however, disclose rate limits, authentication needs, or potential side effects beyond what annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences, front-loading the core purpose and use cases. No unnecessary words or repetition. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description should clarify what the tool returns (e.g., analysis text or structured results). It omits this, leaving the agent to infer. While the purpose is clear, the lack of return value specification is a noticeable gap for a tool performing batch analysis.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions for all 4 parameters. The description reiterates that inputs can be local paths or URLs and can be mixed, but this adds minimal new meaning beyond the schema. Baseline 3 is appropriate since the schema already handles parameter semantics thoroughly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Batch analyze multiple images (2-5) using Google Gemini Vision,' specifying verb and resource with a quantity range. It lists explicit use cases (comparing screenshots, before/after, multi-page documents) and differentiates from the sibling tool 'analyze_image_with_gemini' which handles single images.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use: for multiple images, comparisons, or multi-page documents. It references 'Same privacy rules as analyze_image_with_gemini', providing context. However, it does not explicitly state when not to use or list alternative tools beyond the sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

analyze_image_with_geminiA
Read-only

Analyze a local image file or image URL using Google Gemini Vision.

PRIVACY RULES:

  1. Use this tool ONLY when the current main model cannot natively understand images.

  2. If the current main model has native vision capability, do NOT use this tool unless the user explicitly asks to use Gemini.

  3. Before calling this tool with confirm_send_to_gemini=true, you MUST ask the user for consent.

  4. The image bytes and prompt will be sent to Google Gemini API.

  5. If image_source is a URL, this MCP downloads the image from your machine first, then sends bytes to Gemini.

  6. If the user has not explicitly agreed, omit confirm_send_to_gemini or set it to false to show a confirmation notice only.

Supported inputs:

ParametersJSON Schema
NameRequiredDescriptionDefault
image_sourceYesLocal image path or HTTP/HTTPS image URL. Examples: C:/Users/me/Desktop/a.png or https://example.com/a.png
promptNoWhat to analyze. Example: 'Extract all visible text and summarize the screenshot.'
modelNoOverride the Gemini model for this call. Examples: gemini-2.5-flash, gemini-2.5-pro. Defaults to env GEMINI_VISION_MODEL.
confirm_send_to_geminiNoMust be true only after the user explicitly agrees to send this image to Gemini. Defaults to false.

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true and destructiveHint=false. The description adds key behavioral context: image bytes are sent to Google Gemini API, URL images are downloaded first, and consent is required. This goes beyond annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is verbose, especially the 'PRIVACY RULES' section which repeats consent requirements. While front-loaded with the main purpose, the detailed rules could be condensed. Some sentences could be combined without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers input and behavioral aspects well, but does not explain the output/return format. Since there is no output schema, the agent lacks information on what the tool returns (e.g., text, JSON). This is a significant gap for a tool that produces results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with descriptions for all 4 parameters. The description adds meaningful examples (e.g., image_source paths, prompt text, model overrides) and explains the special behavior of confirm_send_to_gemini. This adds significant value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes images using Gemini Vision, but does not explicitly differentiate from the sibling tool 'analyze_images_batch' (which presumably handles batch processing). The purpose is specific but could be clearer about scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use (only when main model lacks vision) and when-not-to-use (main model has vision, unless user requests). It also mandates user consent before calling with confirm_send_to_gemini=true. These guidelines are thorough and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.3.0
    • First observedanalyze_image_with_gemini
    • First observedanalyze_images_batch
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one for single image analysis and one for batch analysis (2-5 images). There is no overlap, and the descriptions make the difference explicit.

Naming Consistency3/5

Both tools start with 'analyze' but differ in structure: 'analyze_images_batch' uses plural and 'batch' suffix, while 'analyze_image_with_gemini' uses singular and includes 'with_gemini', which is redundant given the server name. This inconsistency in naming conventions reduces clarity.

Tool Count3/5

With only 2 tools, the set feels thin for a vision analysis server. While these cover basic single and batch analysis, more tools (e.g., different analysis types or output formats) would be expected for a well-scoped server.

Completeness3/5

The tools provide basic functionality for image analysis (single and batch), but lack features like returning different output formats, handling streaming, or supporting varied prompts. The surface is minimal and may leave agents needing additional capabilities.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers