Gemini MCP Server

A Model Context Protocol (MCP) server that integrates Google's Gemini API with AI assistants like Claude Desktop, Kiro, Cursor, VS Code, and other MCP-compatible clients.

Features

• Chat: Multi-turn conversations with Gemini models
• Search: Real-time web search using Google Search integration
• Knowledge: Query Gemini's knowledge base (training data)
• Analyze: Analyze code, text, or data with AI-powered insights
• Generate: Generate code, documentation, and creative content
• Latest Models: Support for Gemini 3 preview models (gemini-3-pro-preview, gemini-3-flash-preview)

Prerequisites

• Node.js v20 or later
• A Google Gemini API key (Get one here)

Installation

1. Clone or Download

git clone <your-repo-url>
cd gemini-mcp-server

2. Install Dependencies

npm install
# or
pnpm install

3. Get Your Gemini API Key

1. Visit Google AI Studio
2. Click "Create API Key" or "Get API Key"
3. Copy your API key for use in the configuration steps below

4. Find Your Repository Path

Before configuring MCP clients, you need to get the absolute path to your cloned repository. Run this command in your terminal:

pwd

This will output your current directory path. For example:

/Downloads/projects/gemini-mcp-server

Copy this path - you'll use it in the MCP client configurations below. Replace cloned_repo_location with this actual path in all configuration examples.

Integration with MCP Clients

Kiro

Add this to your Kiro MCP configuration file:

Location: ~/.kiro/settings/mcp.json (user-level) or .kiro/settings/mcp.json (workspace-level)

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/cloned_repo_location/gemini-mcp-server/src/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "GEMINI_MODEL": "gemini-2.5-flash"
      },
      "disabled": false,
      "autoApprove": ["chat", "search", "analyze", "generate", "knowledge"]
    }
  }
}

Note: Replace /cloned_repo_location/gemini-mcp-server with the actual path on your system. You can optionally set GEMINI_MODEL to use a different model (e.g., gemini-3-pro-preview).

After adding the configuration:

1. Open Kiro's MCP Server view in the feature panel
2. Click "Reconnect" on the gemini server, or restart Kiro

Claude Desktop

Add this to your Claude Desktop configuration file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/cloned_repo_location/gemini-mcp-server/src/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "GEMINI_MODEL": "gemini-2.5-flash"
      }
    }
  }
}

After adding the configuration:

1. Restart Claude Desktop completely (quit and reopen)
2. Look for the 🔌 icon in the bottom right to verify the server is connected
3. You can now use Gemini tools in your conversations

Cursor

Add this to your Cursor MCP configuration file:

Location:

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/cloned_repo_location/gemini-mcp-server/src/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "GEMINI_MODEL": "gemini-2.5-flash"
      }
    }
  }
}

After adding the configuration:

1. Restart Cursor
2. Open the Cline extension
3. The Gemini tools should now be available

VS Code (with Cline/Claude Dev Extension)

Add this to your VS Code MCP configuration file:

Location:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/cloned_repo_location/gemini-mcp-server/src/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "GEMINI_MODEL": "gemini-2.5-flash"
      }
    }
  }
}

After adding the configuration:

1. Reload VS Code window (Cmd/Ctrl + Shift + P → "Developer: Reload Window")
2. Open the Cline/Claude Dev extension
3. The Gemini tools should now be available

Other MCP Clients

For any other MCP-compatible client, use the standard MCP server configuration format:

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/cloned_repo_location/gemini-mcp-server/src/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "GEMINI_MODEL": "gemini-2.5-flash"
      }
    }
  }
}

Refer to your specific client's documentation for the exact configuration file location. You can optionally set GEMINI_MODEL to use a different model.

Available Tools

chat

Send messages to Gemini with optional conversation history for multi-turn conversations.

Parameters:

• message (string, required): The message to send to Gemini
• conversationHistory (array, optional): Previous messages in the conversation
  • Format: [{role: "user"|"model", content: "message text"}]

Example:

{
  "message": "What is React?",
  "conversationHistory": [
    {"role": "user", "content": "Hello!"},
    {"role": "model", "content": "Hi! How can I help you today?"}
  ]
}

search

Search for current information using real-time web search powered by Google Search.

Parameters:

• query (string, required): The search query

Example:

{
  "query": "What are the latest AI developments in 2025?"
}

Note: This tool uses Google Search integration for real-time information. If web search is unavailable, it falls back to knowledge base with a warning.

knowledge

Query Gemini's knowledge base (training data) without web search.

Parameters:

• query (string, required): The knowledge query

Example:

{
  "query": "Explain the concept of machine learning"
}

Note: This tool uses only Gemini's training data and doesn't access real-time information.

analyze

Analyze content with AI-powered insights.

Parameters:

• content (string, required): The content to analyze
• analysisType (string, required): Type of analysis
  • Options: code, text, data, general

Example:

{
  "content": "function add(a, b) { return a + b; }",
  "analysisType": "code"
}

generate

Generate content based on a prompt.

Parameters:

• prompt (string, required): The generation prompt
• contentType (string, required): Type of content to generate
  • Options: code, documentation, creative, technical

Example:

{
  "prompt": "Create a React component for a todo list",
  "contentType": "code"
}

Testing the Server

You can test the server directly using Node.js:

# Set your API key
export GEMINI_API_KEY="your_api_key_here"

# Run the server
node src/index.js

The server will start and listen on stdio. You should see:

Gemini MCP Server running on stdio

Development

Run in watch mode for development:

npm run dev

This will automatically restart the server when you make changes to the code.

Configuration Options

Model Selection

By default, the server uses gemini-2.5-flash. To use a different model, set the GEMINI_MODEL environment variable in your MCP configuration:

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/path/to/gemini-mcp-server/src/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "GEMINI_MODEL": "gemini-3-pro-preview"
      }
    }
  }
}

Available models:

Latest (Recommended)

• gemini-3-pro-preview - Latest generation, most capable (preview)
• gemini-3-flash-preview - Latest generation, fast and efficient (preview)

Current Generation

• gemini-2.5-flash - Fast and efficient (default)
• gemini-2.5-pro - More capable, slower

Previous Generation

• gemini-1.5-pro - Previous generation, capable
• gemini-1.5-flash - Previous generation, fast

Note: Preview models (gemini-3-*) are experimental and may have breaking changes. Use production models for stable deployments.

Switching to Gemini 3 Models

To use the latest Gemini 3 preview models, simply set the GEMINI_MODEL environment variable in your MCP configuration:

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/path/to/gemini-mcp-server/src/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "GEMINI_MODEL": "gemini-3-pro-preview"
      }
    }
  }
}

Or for the fast variant:

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/path/to/gemini-mcp-server/src/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "GEMINI_MODEL": "gemini-3-flash-preview"
      }
    }
  }
}

No code changes needed - the server automatically uses the model specified in the environment variable!

Environment Variables

• GEMINI_API_KEY (required): Your Google Gemini API key
• GEMINI_MODEL (optional): The Gemini model to use (default: gemini-2.5-flash)
  • Examples: gemini-3-pro-preview, gemini-3-flash-preview, gemini-2.5-pro, gemini-1.5-pro

Troubleshooting

API Key Error

Error: Error: GEMINI_API_KEY environment variable is not set

Solution: Ensure your API key is properly set in the MCP configuration file under the env section.

Import Error

Error: SyntaxError: The requested module '@google/genai' does not provide an export named 'genai'

Solution: This has been fixed in the latest version. Make sure you're using the correct import:

import { GoogleGenAI } from "@google/genai";

Connection Closed Error

Error: MCP error -32000: Connection closed

Solution:

1. Check that Node.js v20+ is installed: node --version
2. Verify all dependencies are installed: npm install
3. Check that the path in your MCP config is absolute and correct
4. Look at the server logs for more details

Server Not Showing Up

Solution:

1. Verify the configuration file path is correct for your client
2. Ensure the JSON syntax is valid (no trailing commas, proper quotes)
3. Restart your MCP client completely
4. Check the client's logs for error messages

Rate Limiting

If you encounter rate limiting errors from the Gemini API:

1. Check your API quota in Google AI Studio
2. Implement exponential backoff in your requests
3. Consider upgrading your API plan if needed

API Limits

Free tier limits (as of 2025):

• 15 requests per minute
• 1,500 requests per day
• 1 million tokens per minute

For higher limits, check Google AI Studio pricing.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Resources

• Google Gemini API Documentation
• Model Context Protocol Specification
• MCP TypeScript SDK
• Google AI Studio

Support

For issues and questions:

• Open an issue on GitHub
• Check the MCP documentation
• Visit Google AI Studio for API-related questions