Mcp Gemini Server

[](https://mseep.ai/app/bsmi021-mcp-gemini-server)

MCP Gemini Server

Table of Contents

• [Overview](#overview)
• [File Uploads vs URL-Based Analysis](#file-uploads-vs-url-based-analysis)
• [Features](#features)
• [Prerequisites](#prerequisites)
• [Installation & Setup](#installation--setup)
• [Configuration](#configuration)
• [Available Tools](#available-tools)
• [Usage Examples](#usage-examples)
• [Supported Multimedia Analysis Use Cases](#supported-multimedia-analysis-use-cases)
• [MCP Gemini Server and Gemini SDK's MCP Function Calling](#mcp-gemini-server-and-gemini-sdks-mcp-function-calling)
• [Environment Variables](#environment-variables)
• [Security Considerations](#security-considerations)
• [Error Handling](#error-handling)
• [Development and Testing](#development-and-testing)
• [Contributing](#contributing)
• [Code Review Tools](#code-review-tools)
• [Server Features](#server-features)
• [Known Issues](#known-issues)

Overview

This project provides a dedicated MCP (Model Context Protocol) server that wraps the @google/genai SDK (v0.10.0). It exposes Google's Gemini model capabilities as standard MCP tools, allowing other LLMs (like Claude) or MCP-compatible systems to leverage Gemini's features as a backend workhorse.

This server aims to simplify integration with Gemini models by providing a consistent, tool-based interface managed via the MCP standard. It supports the latest Gemini models including gemini-1.5-pro-latest, gemini-1.5-flash, and gemini-2.5-pro models.

Important Note: This server does not support direct file uploads. Instead, it focuses on URL-based multimedia analysis for images and videos. For text-based content processing, use the standard content generation tools.

File Uploads vs URL-Based Analysis

❌ Not Supported: Direct File Uploads

This MCP Gemini Server does not support the following file upload operations:

• Local file uploads: Cannot upload files from your local filesystem to Gemini
• Base64 encoded files: Cannot process base64-encoded image or video data
• Binary file data: Cannot handle raw file bytes or binary data
• File references: Cannot process file IDs or references from uploaded content
• Audio file uploads: Cannot upload and transcribe audio files directly

Why File Uploads Are Not Supported:

• Simplified architecture focused on URL-based processing
• Enhanced security by avoiding file handling complexities
• Reduced storage and bandwidth requirements
• Streamlined codebase maintenance

✅ Fully Supported: URL-Based Multimedia Analysis

This server fully supports analyzing multimedia content from publicly accessible URLs:

Image Analysis from URLs:

• Public image URLs: Analyze images hosted on any publicly accessible web server
• Supported formats: PNG, JPEG, WebP, HEIC, HEIF via direct URL access
• Multiple images: Process multiple image URLs in a single request
• Security validation: Automatic URL validation and security screening

YouTube Video Analysis:

• Public YouTube videos: Full analysis of any public YouTube video content
• Video understanding: Extract insights, summaries, and detailed analysis
• Educational content: Perfect for analyzing tutorials, lectures, and educational videos
• Multiple videos: Process multiple YouTube URLs (up to 10 per request with Gemini 2.5+)

Web Content Processing:

• HTML content: Analyze and extract information from web pages
• Mixed media: Combine text content with embedded images and videos
• Contextual analysis: Process URLs alongside text prompts for comprehensive analysis

Alternatives for Local Content

If you have local files to analyze:

1. Host on a web server: Upload your files to a public web server and use the URL
2. Use cloud storage: Upload to services like Google Drive, Dropbox, or AWS S3 with public access
3. Use GitHub: Host images in a GitHub repository and use the raw file URLs
4. Use image hosting services: Upload to services like Imgur, ImageBB, or similar platforms

For audio content:

• Use external transcription services (Whisper API, Google Speech-to-Text, etc.)
• Upload audio to YouTube and analyze the resulting video URL
• Use other MCP servers that specialize in audio processing

Features

• Core Generation: Standard (gemini_generateContent) and streaming (gemini_generateContentStream) text generation with support for system instructions and cached content.
• Function Calling: Enables Gemini models to request the execution of client-defined functions (gemini_functionCall).
• Stateful Chat: Manages conversational context across multiple turns (gemini_startChat, gemini_sendMessage, gemini_sendFunctionResult) with support for system instructions, tools, and cached content.
• URL-Based Multimedia Analysis: Analyze images from public URLs and YouTube videos without file uploads. Direct file uploads are not supported.
• Caching: Create, list, retrieve, update, and delete cached content to optimize prompts with support for tools and tool configurations.
• Image Generation: Generate images from text prompts using Gemini 2.0 Flash Experimental (gemini_generateImage) with control over resolution, number of images, and negative prompts. Also supports the latest Imagen 3.1 model for high-quality dedicated image generation with advanced style controls. Note that Gemini 2.5 models (Flash and Pro) do not currently support image generation.
• URL Context Processing: Fetch and analyze web content directly from URLs with advanced security, caching, and content processing capabilities.
• gemini_generateContent: Enhanced with URL context support for including web content in prompts
• gemini_generateContentStream: Streaming generation with URL context integration
• gemini_url_analysis: Specialized tool for advanced URL content analysis with multiple analysis types
• MCP Client: Connect to and interact with external MCP servers.
• mcpConnectToServer: Establishes a connection to an external MCP server.
• mcpListServerTools: Lists available tools on a connected MCP server.
• mcpCallServerTool: Calls a function on a connected MCP server, with an option for file output.
• mcpDisconnectFromServer: Disconnects from an external MCP server.
• writeToFile: Writes content directly to files within allowed directories.

Prerequisites

• Node.js (v18 or later)
• An API Key from Google AI Studio ().
• Important: The Caching API is only compatible with Google AI Studio API keys and is not supported when using Vertex AI credentials. This server does not currently support Vertex AI authentication.

Installation & Setup

Installing Manually

1. Clone/Place Project: Ensure the mcp-gemini-server project directory is accessible on your system.
2. Install Dependencies: Navigate to the project directory in your terminal and run:

``bash npm install ``

1. Build Project: Compile the TypeScript source code:

``bash npm run build ``

This command uses the TypeScript compiler (tsc) and outputs the JavaScript files to the ./dist directory (as specified by outDir in tsconfig.json). The main server entry point will be dist/server.js.

1. Generate Connection Token: Create a strong, unique connection token for secure communication between your MCP client and the server. This is a shared secret that you generate and configure on both the server and client sides.

Generate a secure token using one of these methods:

Option A: Using Node.js crypto (Recommended) ``bash node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" ``

Option B: Using OpenSSL ``bash openssl rand -hex 32 ``

Option C: Using PowerShell (Windows) ``powershell [System.Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)) ``

Option D: Online Generator (Use with caution) Use a reputable password generator like 1Password or Bitwarden to generate a 64-character random string.

Important Security Notes:

• The token should be at least 32 characters long and contain random characters
• Never share this token or commit it to version control
• Use a different token for each server instance
• Store the token securely (environment variables, secrets manager, etc.)
• Save this token - you'll need to use the exact same value in both server and client configurations

1. Configure MCP Client: Add the server configuration to your MCP client's settings file (e.g., cline_mcp_settings.json for Cline/VSCode, or claude_desktop_config.json for Claude Desktop App). Replace /path/to/mcp-gemini-server with the actual absolute path on your system, YOUR_API_KEY with your Google AI Studio key, and YOUR_GENERATED_CONNECTION_TOKEN with the token you generated in step 4.

``json { "mcpServers": { "gemini-server": { // Or your preferred name "command": "node", "args": ["/path/to/mcp-gemini-server/dist/server.js"], // Absolute path to the compiled server entry point "env": { "GOOGLE_GEMINI_API_KEY": "YOUR_API_KEY", "MCP_SERVER_HOST": "localhost", // Required: Server host "MCP_SERVER_PORT": "8080", // Required: Server port "MCP_CONNECTION_TOKEN": "YOUR_GENERATED_CONNECTION_TOKEN", // Required: Use the token from step 4 "GOOGLE_GEMINI_MODEL": "gemini-1.5-flash", // Optional: Set a default model // Optional security configurations removed - file operations no longer supported "ALLOWED_OUTPUT_PATHS": "/var/opt/mcp-gemini-server/outputs,/tmp/mcp-gemini-outputs" // Optional: Comma-separated list of allowed output directories for mcpCallServerTool and writeToFileTool }, "disabled": false, "autoApprove": [] } // ... other servers } } ``

Important Notes:

• The path in args must be the absolute path to the compiled dist/server.js file
• MCP_SERVER_HOST, MCP_SERVER_PORT, and MCP_CONNECTION_TOKEN are required unless NODE_ENV is set to test
• MCP_CONNECTION_TOKEN must be the exact same value you generated in step 4
• Ensure the path exists and the server has been built using npm run build

1. Restart MCP Client: Restart your MCP client application (e.g., VS Code with Cline extension, Claude Desktop App) to load the new server configuration. The MCP client will manage starting and stopping the server process.

Configuration

The server uses environment variables for configuration, passed via the env object in the MCP settings:

• GOOGLE_GEMINI_API_KEY (Required): Your API key obtained from Google AI Studio.
• GOOGLE_GEMINI_MODEL (Optional): Specifies a default Gemini model name (e.g., gemini-1.5-flash, gemini-1.0-pro). If set, tools that require a model name (like gemini_generateContent, gemini_startChat, etc.) will use this default when the modelName parameter is omitted in the tool call. This simplifies client calls when primarily using one model. If this environment variable is not set, the modelName parameter becomes required for those tools. See the Google AI documentation for available model names.
• ALLOWED_OUTPUT_PATHS (Optional): A comma-separated list of absolute paths to directories where the mcpCallServerTool (with outputToFile parameter) and writeToFileTool are allowed to write files. If not set, file output will be disabled for these tools. This is a security measure to prevent arbitrary file writes.

Available Tools

This server provides the following MCP tools. Parameter schemas are defined using Zod for validation and description.

Validation and Error Handling: All parameters are validated using Zod schemas at both the MCP tool level and service layer, providing consistent validation, detailed error messages, and type safety. The server implements comprehensive error mapping to provide clear, actionable error messages.

Retry Logic: API requests automatically use exponential backoff retry for transient errors (network issues, rate limits, timeouts), improving reliability for unstable connections. The retry mechanism includes configurable parameters for maximum attempts, delay times, and jitter to prevent thundering herd effects.

Note on Optional Parameters: Many tools accept complex optional parameters (e.g., generationConfig, safetySettings, toolConfig, history, functionDeclarations, contents). These parameters are typically objects or arrays whose structure mirrors the types defined in the underlying @google/genai SDK (v0.10.0). For the exact structure and available fields within these complex parameters, please refer to:

1. The corresponding src/tools/*Params.ts file in this project.
2. The official Google AI JS SDK Documentation.

Core Generation

• gemini_generateContent
• Description: Generates non-streaming text content from a prompt with optional URL context support.
• Required Params: prompt (string)
• Optional Params:
• modelName (string) - Name of the model to use
• generationConfig (object) - Controls generation parameters like temperature, topP, etc.
• thinkingConfig (object) - Controls model reasoning process
• thinkingBudget (number) - Maximum tokens for reasoning (0-24576)
• reasoningEffort (string) - Simplified control: "none" (0 tokens), "low" (1K), "medium" (8K), "high" (24K)
• safetySettings (array) - Controls content filtering by harm category
• systemInstruction (string or object) - System instruction to guide model behavior
• cachedContentName (string) - Identifier for cached content to use with this request
• urlContext (object) - Fetch and include web content from URLs
• urls (array) - URLs to fetch and include as context (max 20)
• fetchOptions (object) - Configuration for URL fetching
• maxContentKb (number) - Maximum content size per URL in KB (default: 100)
• timeoutMs (number) - Fetch timeout per URL in milliseconds (default: 10000)
• includeMetadata (boolean) - Include URL metadata in context (default: true)
• convertToMarkdown (boolean) - Convert HTML to markdown (default: true)
• allowedDomains (array) - Specific domains to allow for this request
• userAgent (string) - Custom User-Agent header for URL requests
• modelPreferences (object) - Model selection preferences
• Note: Can handle multimodal inputs, cached content, and URL context for comprehensive content generation
• Thinking Budget: Controls the token budget for model reasoning. Lower values provide faster responses, higher values improve complex reasoning.
• gemini_generateContentStream
• Description: Generates text content via streaming using Server-Sent Events (SSE) for real-time content delivery with URL context support.
• Required Params: prompt (string)
• Optional Params:
• modelName (string) - Name of the model to use
• generationConfig (object) - Controls generation parameters like temperature, topP, etc.
• thinkingConfig (object) - Controls model reasoning process
• thinkingBudget (number) - Maximum tokens for reasoning (0-24576)
• reasoningEffort (string) - Simplified control: "none" (0 tokens), "low" (1K), "medium" (8K), "high" (24K)
• safetySettings (array) - Controls content filtering by harm category
• systemInstruction (string or ob

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bsmi021
• Source: bsmi021/mcp-gemini-server
• License: MIT

Install and usage instructions live in the source repository linked above.