MCP Gemini Server
Table of Contents
- Overview
- File Uploads vs URL-Based Analysis
- Features
- Prerequisites
- Installation & Setup
- Configuration
- Available Tools
- Usage Examples
- Supported Multimedia Analysis Use Cases
- MCP Gemini Server and Gemini SDK's MCP Function Calling
- Environment Variables
- Security Considerations
- Error Handling
- Development and Testing
- Contributing
- Code Review Tools
- Server Features
- 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:
- Host on a web server: Upload your files to a public web server and use the URL
- Use cloud storage: Upload to services like Google Drive, Dropbox, or AWS S3 with public access
- Use GitHub: Host images in a GitHub repository and use the raw file URLs
- 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 promptsgemini_generateContentStream: Streaming generation with URL context integrationgemini_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
- Clone/Place Project: Ensure the
mcp-gemini-serverproject directory is accessible on your system. -
Install Dependencies: Navigate to the project directory in your terminal and run:
bash npm install -
Build Project: Compile the TypeScript source code:
bash npm run buildThis command uses the TypeScript compiler (
tsc) and outputs the JavaScript files to the./distdirectory (as specified byoutDirintsconfig.json). The main server entry point will bedist/server.js.
4. 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 32Option C: Using PowerShell (Windows)```powershell
```
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 -
Configure MCP Client: Add the server configuration to your MCP client's settings file (e.g.,
cline_mcp_settings.jsonfor Cline/VSCode, orclaude_desktop_config.jsonfor Claude Desktop App). Replace/path/to/mcp-gemini-serverwith the actual absolute path on your system,YOUR_API_KEYwith your Google AI Studio key, andYOUR_GENERATED_CONNECTION_TOKENwith 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 inargsmust be the absolute path to the compileddist/server.jsfile
-MCP_SERVER_HOST,MCP_SERVER_PORT, andMCP_CONNECTION_TOKENare required unlessNODE_ENVis set totest
-MCP_CONNECTION_TOKENmust be the exact same value you generated in step 4
- Ensure the path exists and the server has been built usingnpm run build
6. 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 (likegemini_generateContent,gemini_startChat, etc.) will use this default when themodelNameparameter is omitted in the tool call. This simplifies client calls when primarily using one model. If this environment variable is not set, themodelNameparameter 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 themcpCallServerTool(withoutputToFileparameter) andwriteToFileToolare 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 usegenerationConfig(object) - Controls generation parameters like temperature, topP, etc.thinkingConfig(object) - Controls model reasoning processthinkingBudget(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 categorysystemInstruction(string or object) - System instruction to guide model behaviorcachedContentName(string) - Identifier for cached content to use with this requesturlContext(object) - Fetch and include web content from URLsurls(array) - URLs to fetch and include as context (max 20)fetchOptions(object) - Configuration for URL fetchingmaxContentKb(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 requestuserAgent(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 usegenerationConfig(object) - Controls generation parameters like temperature, topP, etc.thinkingConfig(object) - Controls model reasoning processthinkingBudget(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 categorysystemInstruction(string or object) - System instruction to guide model behaviorcachedContentName(string) - Identifier for cached content to use with this requesturlContext(object) - Same URL context options asgemini_generateContentmodelPreferences(object) - Model selection preferences
Function Calling
gemini_functionCall- Description: Sends a prompt and function declarations to the model, returning either a text response or a requested function call object (as a JSON string).
- Required Params:
prompt(string),functionDeclarations(array) - Optional Params:
modelName(string) - Name of the model to usegenerationConfig(object) - Controls generation parameterssafetySettings(array) - Controls content filteringtoolConfig(object) - Configures tool behavior like temperature and confidence thresholds
Stateful Chat
gemini_startChat- Description: Initiates a new stateful chat session and returns a unique
sessionId. - Optional Params:
modelName(string) - Name of the model to usehistory(array) - Initial conversation historytools(array) - Tool definitions including function declarationsgenerationConfig(object) - Controls generation parametersthinkingConfig(object) - Controls model reasoning processthinkingBudget(number) - Maximum tokens for reasoning (0-24576)reasoningEffort(string) - Simplified control: "none" (0 tokens), "low" (1K), "medium" (8K), "high" (24K)
safetySettings(array) - Controls content filteringsystemInstruction(string or object) - System instruction to guide model behaviorcachedContentName(string) - Identifier for cached content to use with this session
gemini_sendMessage- Description: Sends a message within an existing chat session.
- Required Params:
sessionId(string),message(string) - Optional Params:
generationConfig(object) - Controls generation parametersthinkingConfig(object) - Controls model reasoning processthinkingBudget(number) - Maximum tokens for reasoning (0-24576)reasoningEffort(string) - Simplified control: "none" (0 tokens), "low" (1K), "medium" (8K), "high" (24K)
safetySettings(array) - Controls content filteringtools(array) - Tool definitions including function declarationstoolConfig(object) - Configures tool behaviorcachedContentName(string) - Identifier for cached content to use with this message
gemini_sendFunctionResult- Description: Sends the result of a function execution back to a chat session.
- Required Params:
sessionId(string),functionResponse(string) - The result of the function execution - Optional Params:
functionCall(object) - Reference to the original function call gemini_routeMessage- Description: Routes a message to the most appropriate model from a provided list based on message content. Returns both the model's response and which model was selected.
- Required Params:
message(string) - The text message to be routed to the most appropriate modelmodels(array) - Array of model names to consider for routing (e.g., ['gemini-1.5-flash', 'gemini-1.5-pro']). The first model in the list will be used for routing decisions.
- Optional Params:
routingPrompt(string) - Custom prompt to use for routing decisions. If not provided, a default routing prompt will be used.defaultModel(string) - Model to fall back to if routing fails. If not provided and routing fails, an error will be thrown.generationConfig(object) - Generation configuration settings to apply to the selected model's response.thinkingConfig(object) - Controls model reasoning processthinkingBudget(number) - Maximum tokens for reasoning (0-24576)reasoningEffort(string) - Simplified control: "none" (0 tokens), "low" (1K), "medium" (8K), "high" (24K)
safetySettings(array) - Safety settings to apply to both routing and final response.systemInstruction(string or object) - A system instruction to guide the model's behavior after routing.
Remote File Operations (Removed)
Note: Direct file upload operations are no longer supported by this server. The server now focuses exclusively on URL-based multimedia analysis for images and videos, and text-based content generation.
Alternative Approaches:
- For Image Analysis: Use publicly accessible image URLs with gemini_generateContent or gemini_url_analysis tools
- For Video Analysis: Use publicly accessible YouTube video URLs for content analysis
- For Audio Content: Audio transcription via file uploads is not supported - consider using URL-based services that provide audio transcripts
- For Document Analysis: Use URL-based document analysis or convert documents to publicly accessible formats
Caching (Google AI Studio Key Required)
gemini_createCache- Description: Creates cached content for compatible models (e.g.,
gemini-1.5-flash). - Required Params:
contents(array),model(string) - Optional Params:
displayName(string) - Human-readable name for the cached contentsystemInstruction(string or object) - System instruction to apply to the cached contentttl(string - e.g., '3600s') - Time-to-live for the cached contenttools(array) - Tool definitions for use with the cached contenttoolConfig(object) - Configuration for the tools
gemini_listCaches- Description: Lists existing cached content.
- Required Params: None
- Optional Params:
pageSize(number),pageToken(string - Note:pageTokenmay not be reliably returned currently). gemini_getCache- Description: Retrieves metadata for specific cached content.
- Required Params:
cacheName(string - e.g.,cachedContents/abc123xyz) gemini_updateCache- Description: Updates metadata and contents for cached content.
- Required Params:
cacheName(string),contents(array) - Optional Params:
displayName(string) - Updated display namesystemInstruction(string or object) - Updated system instructionttl(string) - Updated time-to-livetools(array) - Updated tool definitionstoolConfig(object) - Updated tool configuration
gemini_deleteCache- Description: Deletes cached content.
- Required Params:
cacheName(string - e.g.,cachedContents/abc123xyz)
Image Generation
gemini_generateImage- Description: Generates images from text prompts using available image generation models.
- Required Params:
prompt(string - descriptive text prompt for image generation) - Optional Params:
modelName(string - defaults to "imagen-3.1-generate-003" for high-quality dedicated image generation or use "gemini-2.0-flash-exp-image-generation" for Gemini models)resolution(string enum: "512x512", "1024x1024", "1536x1536")numberOfImages(number - 1-8, default: 1)safetySettings(array) - Controls content filtering for generated imagesnegativePrompt(string - features to avoid in the generated image)stylePreset(string enum: "photographic", "digital-art", "cinematic", "anime", "3d-render", "oil-painting", "watercolor", "pixel-art", "sketch", "comic-book", "neon", "fantasy")seed(number - integer value for reproducible generation)styleStrength(number - strength of style preset, 0.0-1.0)
- Response: Returns an array of base64-encoded images with metadata including dimensions and MIME type.
- Notes: Image generation uses significant resources, especially at higher resolutions. Consider using smaller resolutions for faster responses and less resource usage.
Audio Transcription (Removed)
Note: Audio transcription via direct file uploads is no longer supported by this server. The server focuses on URL-based multimedia analysis for images and videos.
Alternative Approaches for Audio Content:
- YouTube Videos: Use the YouTube video analysis capabilities to analyze video content that includes audio
- External Services: Use dedicated audio transcription services and analyze their output as text content
- URL-Based Audio: If audio content is available via public URLs in supported formats, consider using external transcription services first, then analyze the resulting text
URL Content Analysis
gemini_url_analysis- Description: Advanced URL analysis tool that fetches content from web pages and performs specialized analysis tasks with comprehensive security and performance optimizations.
- Required Params:
urls(array) - URLs to analyze (1-20 URLs supported)analysisType(string enum) - Type of analysis to perform:summary- Comprehensive content summarizationcomparison- Multi-URL content comparisonextraction- Structured information extractionqa- Question-based content analysissentiment- Emotional tone analysisfact-check- Credibility assessmentcontent-classification- Topic and type categorizationreadability- Accessibility and complexity analysisseo-analysis- Search optimization evaluation
- Optional Params:
query(string) - Specific query or instruction for the analysisextractionSchema(object) - JSON schema for structured data extractionquestions(array) - List of specific questions to answer (for Q&A analysis)compareBy(array) - Specific aspects to compare when using comparison analysisoutputFormat(string enum: "text", "json", "markdown", "structured") - Desired output formatincludeMetadata(boolean) - Include URL metadata in the analysis (default: true)fetchOptions(object) - Advanced URL fetching options (same as urlContext fetchOptions)modelName(string) - Specific Gemini model to use (auto-selected if not specified)
- Security Features: Multi-layer URL validation, domain restrictions, private network protection, and rate limiting
- Performance Features: Intelligent caching, concurrent processing, and optimal model selection based on content complexity
MCP Client Tools
mcpConnectToServer- Description: Establishes a connection to an external MCP server and returns a connection ID.
- Required Params:
serverId(string): A unique identifier for this server connection.connectionType(string enum: "sse" | "stdio"): The transport protocol to use.sseUrl(string, optional ifconnectionTypeis "stdio"): The URL for SSE connection.stdioCommand(string, optional ifconnectionTypeis "sse"): The command to run for stdio connection.stdioArgs(array of strings, optional): Arguments for the stdio command.stdioEnv(object, optional): Environment variables for the stdio command.
- Important: This tool returns a
connectionIdthat must be used in subsequent calls tomcpListServerTools,mcpCallServerTool, andmcpDisconnectFromServer. ThisconnectionIdis generated internally and is different from theserverIdparameter. mcpListServerTools- Description: Lists available tools on a connected MCP server.
- Required Params:
connectionId(string): The connection identifier returned bymcpConnectToServer.
mcpCallServerTool- Description: Calls a function on a connected MCP server.
- Required Params:
connectionId(string): The connection identifier returned bymcpConnectToServer.toolName(string): The name of the tool to call on the remote server.toolArgs(object): The arguments to pass to the remote tool.
- Optional Params:
outputToFile(string): If provided, the tool's output will be written to this file path. The path must be within one of the directories specified in theALLOWED_OUTPUT_PATHSenvironment variable.
mcpDisconnectFromServer- Description: Disconnects from an external MCP server.
- Required Params:
connectionId(string): The connection identifier returned bymcpConnectToServer.
writeToFile- Description: Writes content directly to a file.
- Required Params:
filePath(string): The absolute path of the file to write to. Must be within one of the directories specified in theALLOWED_OUTPUT_PATHSenvironment variable.content(string): The content to write to the file.
- Optional Params:
overwrite(boolean, default: false): If true, overwrite the file if it already exists. Otherwise, an error will be thrown if the file exists.
Usage Examples
Here are examples of how an MCP client (like Claude) might call these tools using the use_mcp_tool format:
Example 1: Simple Content Generation (Using Default Model)```xml
<use_mcp_tool>
<server_name>gemini-server</server_name>
<tool_name>gemini_generateContent</tool_name>
<arguments>
{
"prompt": "Write a short poem about a rubber duck."
}
</arguments>
</use_mcp_tool>
**Example 2: Content Generation (Specifying Model & Config)**```xml
<use_mcp_tool>
<server_name>gemini-server</server_name>
<tool_name>gemini_generateContent</tool_name>
<arguments>
{
"modelName": "gemini-1.0-pro",
"prompt": "Explain the concept of recursion in programming.",
"generationConfig": {
"temperature": 0.7,
"maxOutputTokens": 500
}
}
</arguments>
</use_mcp_tool>
Example 2b: Content Generation with Thinking Budget Control```xml
<use_mcp_tool>
<server_name>gemini-server</server_name>
<tool_name>gemini_generateContent</tool_name>
<arguments>
{
"modelName": "gemini-1.5-pro",
"prompt": "Solve this complex math problem: Find all values of x where 2sin(x) = x^2-x+1 in the range [0, 2π].",
"generationConfig": {
"temperature": 0.2,
"maxOutputTokens": 1000,
"thinkingConfig": {
"thinkingBudget": 8192
}
}
}
</arguments>
</use_mcp_tool>
**Example 2c: Content Generation with Simplified Reasoning Effort**```xml
<use_mcp_tool>
<server_name>gemini-server</server_name>
<tool_name>gemini_generateContent</tool_name>
<arguments>
{
"modelName": "gemini-1.5-pro",
"prompt": "Solve this complex math problem: Find all values of x where 2sin(x) = x^2-x+1 in the range [0, 2π].",
…(正文过长,页面只展示前面部分,完整内容见仓库)