MCP Gemini Server

You run an MCP server that wraps Google's Gemini capabilities, exposing them as ready-to-use MCP tools for other LLMs and MCP-compatible systems. This server centralizes model access, enforces security, and provides a consistent API surface for text generation, chat, image generation, URL-based content analysis, and more. It focuses on URL-based multimedia analysis and text generation workflows, making Gemini features available via standard MCP calls without requiring direct Gemini SDK usage in each client.

How to use

Your MCP client connects to the Gemini MCP server and calls the pre-defined tools to generate text, start chats, analyze content from URLs, generate images, or perform advanced URL content analyses. You use a single, consistent set of MCP tools to access Gemini capabilities, manage session state, cache results, and optionally connect to other external MCP servers.

How to install

# Prerequisites
- Node.js (v18 or later)
- An API Key from Google AI Studio

# 1. Install dependencies
npm install

# 2. Build the project
npm run build

# 3. Run in development (example)
npm run dev

Configuration

Configure the server via environment variables and MCP client settings. The key required variables are the Gemini API key and the server connection details. The main required variables are GO... GEMINI API KEY, MCP_SERVER_HOST, MCP_SERVER_PORT, and MCP_CONNECTION_TOKEN. Optional defaults let you set a default Gemini model and enable URL context with sensible caching and security options.

Environment variables you configure include:

• GOOGLE_GEMINI_API_KEY: Your Google Gemini API key
• MCP_SERVER_HOST: Server host address (e.g., localhost)
• MCP_SERVER_PORT: Port for network transports (e.g., 8080)
• MCP_CONNECTION_TOKEN: A strong, unique shared secret for client connections
• GOOGLE_GEMINI_MODEL: Optional default Gemini model name
• ALLOWED_OUTPUT_PATHS: Optional comma-separated absolute paths for allowed write locations
• GO...GEMINI_ENABLE_URL_CONTEXT, GO...URL_MAX_COUNT, GO...URL_MAX_CONTENT_KB, GO...URL_FETCH_TIMEOUT_MS, GO...URL_ALLOWED_DOMAINS, GO...URL_BLOCKLIST, GO...URL_CONVERT_TO_MARKDOWN, GO...URL_INCLUDE_METADATA, GO...URL_ENABLE_CACHING, GO...URL_USER_AGENT: Optional URL context controls
• ENABLE_HEALTH_CHECK, HEALTH_CHECK_PORT: Health check endpoint controls
• MCP_TRANSPORT, MCP_LOG_LEVEL, MCP_ENABLE_STREAMING, SESSION_STORE_TYPE, SQLITE_DB_PATH: Transport, logging, streaming, session storage These variables can be set in a .env file or injected by your environment manager.

Security and best practices

Follow security practices to protect tokens, keys, and write permissions. Use absolute paths for any write locations, enable URL context only when needed, and restrict allowed domains. Run the server with restricted user permissions and consider containerization for isolation. Rotate credentials regularly and store secrets in a secure secrets manager.

Examples and common workflows

Use publicly accessible URLs to analyze images, YouTube videos, or web pages. Generate text or images from prompts, perform URL-based analyses, and optionally manage caches of content for reuse in prompts.

Troubleshooting and notes

If you encounter authentication errors, verify GOOGLE_GEMINI_API_KEY and MCP_CONNECTION_TOKEN. For rate limits or transient network issues, the server includes retry logic with exponential backoff. Check that ALLOWED_OUTPUT_PATHS is correctly set if you need file outputs. If URL-context features are required, ensure GO...GEMINI_ENABLE_URL_CONTEXT is set to true and domain allowlists are configured conservatively for production.

Finish setup and start using the MCP server

After building, configure your MCP client with the stdio server entry shown in the deployment example, then start the server as a local process. The client will manage the server lifecycle and route your MCP tool calls to the Gemini capabilities behind the scenes.

Notes on maintenance and growth

This server provides a broad set of MCP tools, including generation, chat, function calling, URL analysis, cache management, image generation, and inter-server tool calls. You can extend usage by connecting to external MCP servers via the included client tools and routing content through Gemini tools as needed.

Available tools

gemini_generateContent

Generates non-streaming text content from a prompt, with optional URL context and multimodal inputs.

gemini_generateContentStream

Generates streaming text content using Server-Sent Events with URL context support.

gemini_functionCall

Sends a prompt and function declarations to the model and returns a text response or a function call instruction.

gemini_startChat

Initiates a stateful chat session and returns a session identifier for subsequent messages.

gemini_sendMessage

Sends a message within an existing chat session.

gemini_sendFunctionResult

Sends the result of a function execution back to a chat session.

gemini_routeMessage

Routes a message to the most appropriate model from a provided model list and returns the chosen model.

gemini_createCache

Creates cached content for compatible models to reuse in future prompts.

gemini_listCaches

Lists existing cached content entries.

gemini_getCache

Retrieves metadata for a specific cached content entry.

gemini_updateCache

Updates metadata and contents for cached content.

gemini_deleteCache

Deletes cached content.

gemini_generateImage

Generates images from text prompts with multiple image generation options.

gemini_url_analysis

Performs advanced analysis of content fetched from public URLs, including extraction, summary, and more.

mcpConnectToServer

Connects to an external MCP server and returns a connection identifier.

mcpListServerTools

Lists available tools on a connected MCP server.

mcpCallServerTool

Calls a tool on a connected MCP server and can write output to a file.

mcpDisconnectFromServer

Disconnects from a connected MCP server.

writeToFile

Writes content directly to files within allowed directories.