home / mcp / mcp gemini server
This project provides a dedicated MCP (Model Context Protocol) server that wraps the @google/genai SDK. It exposes Google's Gemini model capabilities as standard MCP tools, allowing other LLMs (like Cline) or MCP-compatible systems to leverage Gemini's features as a backend workhorse.
Configuration
View docs{
"mcpServers": {
"bsmi021-mcp-gemini-server": {
"command": "node",
"args": [
"/path/to/mcp-gemini-server/dist/server.js"
],
"env": {
"MCP_SERVER_HOST": "localhost",
"MCP_SERVER_PORT": "8080",
"GOOGLE_GEMINI_MODEL": "gemini-1.5-flash",
"ALLOWED_OUTPUT_PATHS": "/var/opt/mcp-gemini-server/outputs,/tmp/mcp-gemini-outputs",
"MCP_CONNECTION_TOKEN": "YOUR_GENERATED_CONNECTION_TOKEN",
"GOOGLE_GEMINI_API_KEY": "YOUR_API_KEY"
}
}
}
}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.
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.
# 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 devConfigure 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.
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.
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.
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.
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.
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.
Generates non-streaming text content from a prompt, with optional URL context and multimodal inputs.
Generates streaming text content using Server-Sent Events with URL context support.
Sends a prompt and function declarations to the model and returns a text response or a function call instruction.
Initiates a stateful chat session and returns a session identifier for subsequent messages.
Sends a message within an existing chat session.
Sends the result of a function execution back to a chat session.
Routes a message to the most appropriate model from a provided model list and returns the chosen model.
Creates cached content for compatible models to reuse in future prompts.
Lists existing cached content entries.
Retrieves metadata for a specific cached content entry.
Updates metadata and contents for cached content.
Deletes cached content.
Generates images from text prompts with multiple image generation options.
Performs advanced analysis of content fetched from public URLs, including extraction, summary, and more.
Connects to an external MCP server and returns a connection identifier.
Lists available tools on a connected MCP server.
Calls a tool on a connected MCP server and can write output to a file.
Disconnects from a connected MCP server.
Writes content directly to files within allowed directories.