Skip to main content
Glama

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:

  • web

  • remote_file

  • local_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:

  • image

  • video

  • audio

  • document

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:

  • image

  • video

  • audio

  • document

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:

  1. resolves relative paths against its working directory;

  2. uploads the file through the Gemini Files API;

  3. waits until processing is complete;

  4. sends the uploaded URI using the declared source type;

  5. 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: high

GEMINI_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-studio

Custom 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-mcp

With 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-mcp

Local development

npm install
npm test
npm run build

Run the stdio server:

GEMINI_API_KEY=YOUR_KEY npm start

The 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 tools
audioGemini audio understandingA
Read-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 understandingA
Read-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 understandingA
Read-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 understandingA
Read-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 researchA
Read-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

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tool names follow the same simple pattern: single lowercase nouns representing the input type. This is perfectly consistent and intuitive.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Minimal 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      1
      MIT