gemini-understanding
This server provides independent, one-shot Gemini requests: web research plus analysis of a single video, audio, document, or image source.
Run web research with Google Search and URL Context enabled by supplying a prompt, including ordinary webpage URLs directly in the prompt.
Analyze one video from a public YouTube URL, direct remote video URL, or local server-side path using the
videotool.Analyze one audio, document, or image from a direct remote URL or local server-side path using the corresponding modality tool.
Provide an optional MIME type hint, especially for direct remote files; omit it for YouTube or local files when inference is sufficient.
Use local paths only on the MCP server filesystem, not the client filesystem unless storage is shared/mounted.
Each call sends one prompt and at most one source, returns one answer, and does not maintain conversation history across calls.
The caller declares the source modality; the server does not inspect, reclassify, download, convert, or fall back across source types.
Leverages Google's Gemini API for web and multimodal understanding, including web research with Google Search and URL Context, and analysis of video, audio, documents, and images.
Processes YouTube video URLs to provide summaries, descriptions, or answers about video content using Gemini's video understanding capabilities.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gemini-understanding Summarize this video and give me the key takeaways"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gemini MCP
A minimal MCP server for one-shot Gemini requests. Each tool call sends one prompt and at most one source, returns one answer, and does not link calls into a continuing conversation.
The server exposes three independent tools:
webremote_filelocal_file
Clients and MCP gateways may expose any subset of the tools. This is useful for remote or isolated deployments where filesystem access is unavailable or undesirable: local_file can be hidden without changing the contract of the remaining tools.
web
Performs one-shot web research with both Gemini server tools enabled:
Google Search
URL Context
Input:
{
"prompt": "Research the topic and read https://example.com/page"
}Ordinary webpage URLs may be included directly in the prompt.
Related MCP server: Sibyl
remote_file
Analyzes one public HTTP(S) file URL. The caller must declare the source type; the server does not inspect the URL or reclassify the source.
Input:
{
"url": "https://example.com/report.pdf",
"type": "document",
"prompt": "Summarize the conclusions",
"mimeType": "application/pdf"
}type is required and must be one of:
imagevideoaudiodocument
mimeType is optional, but it is preferred for direct remote files when known because origin servers may return missing, generic, malformed, or parameterized MIME metadata. Public YouTube URLs are supplied with type: "video" and normally omit mimeType.
Examples:
{
"url": "https://www.youtube.com/watch?v=...",
"type": "video",
"prompt": "Summarize this video"
}Video understanding always uses Gemini agentic video processing and requires Gemini 3.5 Flash Lite or newer. Older models are not supported for video requests.
{
"url": "https://example.com/audio.mp3",
"type": "audio",
"prompt": "Transcribe the speech",
"mimeType": "audio/mpeg"
}The URL is passed directly to Gemini as a typed URI. The server performs no HTTP header probing, MIME sniffing, extension-based routing, downloading, conversion, or cross-type fallback.
local_file
Analyzes one file available on the MCP server filesystem. The caller must declare the source type; the server does not inspect the content or reclassify the source.
Input:
{
"path": "/workspace/report.pdf",
"type": "document",
"prompt": "Summarize the conclusions"
}type is required and must be one of:
imagevideoaudiodocument
mimeType is optional. The Gemini SDK normally infers it from a recognized file extension. It may be supplied as an override when inference is unavailable or incorrect.
The server:
resolves relative paths against its working directory;
uploads the file through the Gemini Files API;
waits until processing is complete;
sends the uploaded URI using the declared source type;
deletes the temporary upload.
The path refers to the filesystem visible to the MCP server process. In a remote, containerized, or isolated deployment, it does not refer to the MCP client's filesystem unless that storage is explicitly mounted or shared.
Configuration
GEMINI_API_KEY required
GEMINI_BASE_URL optional; default: official Google Gemini API endpoint
GEMINI_MODEL default: gemini-3.5-flash-lite
GEMINI_THINKING_LEVEL default: highGEMINI_BASE_URL replaces the Gemini API base URL used by the Google Gen AI SDK. Leave it unset to use Google's official endpoint. This is useful with compatible reverse proxies or API gateways, for example:
GEMINI_BASE_URL=https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/google-ai-studioCustom model and thinking-level strings are passed through without compatibility validation.
Install from GitHub
claude mcp add gemini-mcp -s user -- \
env GEMINI_API_KEY=YOUR_KEY \
npx -y github:sandlong/gemini-mcpWith explicit optional settings:
claude mcp add gemini-mcp -s user -- \
env GEMINI_API_KEY=YOUR_KEY \
GEMINI_BASE_URL=https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/google-ai-studio \
GEMINI_MODEL=gemini-3.5-flash-lite \
GEMINI_THINKING_LEVEL=high \
npx -y github:sandlong/gemini-mcpLocal development
npm install
npm test
npm run buildRun the stdio server:
GEMINI_API_KEY=YOUR_KEY npm startThe stdio implementation can also be placed behind an MCP gateway that exposes it through Streamable HTTP. Tool filtering remains a client or gateway concern.
Error behavior
The server does not silently correct or reroute failed requests. Tool errors include the tool name, processing stage, configured model, thinking level, source, and the original Gemini status, code, and message when available.
A nonexistent server-side path fails at the filesystem stage because no API request can be constructed. Temporary-upload cleanup failures are non-fatal and are reported as warnings.
Available Tools
5 toolsaudioGemini audio understandingARead-only
Understand one audio source from a direct remote URL or local path. The caller chooses this modality; the server does not reclassify the source.
Inputs: prompt (required), source (required), mimeType.
documentGemini document understandingARead-only
Understand one document source, such as a PDF, CSV, or text document, from a direct remote URL or local path. The caller chooses this modality; the server does not reclassify the source.
Inputs: prompt (required), source (required), mimeType.
imageGemini image understandingARead-only
Understand one image source from a direct remote URL or local path. The caller chooses this modality; the server does not reclassify the source.
Inputs: prompt (required), source (required), mimeType.
videoGemini video understandingARead-only
Understand one video source. Accepts a public YouTube URL, a direct remote video URL, or a local video path. The caller chooses this modality; the server does not reclassify the source.
Inputs: prompt (required), source (required), mimeType.
webGemini web researchARead-only
Use Gemini with both Google Search and URL Context enabled. Put ordinary webpage URLs directly in the prompt. Use video, audio, document, or image for typed media and file inputs.
Inputs: prompt (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool corresponds to a distinct input modality (web, video, audio, document, image), and descriptions explicitly state the caller chooses the modality. There is no overlap or ambiguity between tools.
All tool names follow the same simple pattern: single lowercase nouns representing the input type. This is perfectly consistent and intuitive.
Five tools cover the primary media types for the server's 'understanding' purpose without unnecessary duplication. The scope is well-matched to common multimodal input needs.
The set covers the full range of typical input media—web pages, video, audio, documents, and images. There are no obvious missing modalities that would hinder the server's stated purpose.
Maintenance
Related MCP Connectors
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMinimal MCP server that provides access to Google's Gemini API with Google Search grounding for up-to-date information through a single ask_gemini tool.MIT
- AlicenseAqualityCmaintenanceMCP server for Google's Gemini API, enabling text, image, video, speech, embeddings, and deep research capabilities through a single tool set.10MIT
- AlicenseNot gradedqualityDmaintenanceRemote MCP server that exposes Google Gemini's text, image, video (Veo), and audio transcription capabilities as tools any MCP client can call directly.ISC
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets AI assistants use Google's Gemini models. Generate text, analyze images, review code, and more — with support for multi-turn conversations and web-grounded answers.1MIT