Gemini MCP Server: Free AI Search & Grounding for VS Code

Open-source Perplexity alternative for developers. Connect VS Code Copilot, Cline, or Roo to Google Search and Deep Web Analysis via the Model Context Protocol (MCP).

---

📖 Table of Contents

• Why use this?
• How it Works
• Key Features
• Available Tools
• Quick Start
• Configuration
• Comparison
• Troubleshooting

---

Why use this Gemini MCP Server?

This is a Model Context Protocol (MCP) server that upgrades your AI coding assistant (like VS Code GitHub Copilot, Cline, or Roo Code). It provides real-time Internet access and deep web page analysis using Google's Gemini 2.5 Flash API.

It uses Google Search Grounding, allowing your LLM to fetch factual answers from the web without hallucinating.

Benefits:

• Perplexity in your IDE: Ask "What is the latest Next.js 15 breaking change?" and get a cited answer without leaving VS Code.
• Free to run: Uses the Google AI Studio free tier (1,500 requests/day).
• Deep Context: Doesn't just read snippets; it uses Gemini's url_context to read full documentation pages, PDFs, and technical blogs.

How it Works (Grounding Architecture)

graph LR
    A[User in VS Code] -->|Asks Question| B(Copilot / MCP Client);
    B -->|Routes Query| C[Gemini MCP Server];
    C -->|API Call| D[Gemini API];
    D -->|1. Search & Retrieve| E[Google Search / Web Index];
    D -->|2. Augment Context| D;
    D -->|3. Generate Answer| B;
    B -->|Final Answer| A;

Loading

---

Key Features

• 🔍 Grounding with Google Search: Uses the official Google Search Grounding for factual, up-to-date results.
• 📄 Deep URL Analysis: Uses Gemini's URL Context to read large documents (HTML, PDF) for summarization and QA.
• 📚 Citations & Sources: Every claim is backed by a clickable link, distinguishing it from standard LLM hallucinations.
• 🎯 Pre-configured Prompts: Ready-to-use templates for common research and analysis tasks.
• 📊 Resource Access: Query server capabilities and information dynamically.
• ✅ Standard MCP Protocol: Compatible with any MCP client, including Cursor, Windsurf, and VS Code.
• ⚡ Low Latency: Powered by gemini-2.5-flash, optimized for speed and low cost.
• 🆓 100% Free Tier: Works with the free Google AI Studio API key (no credit card required).

---

Available Tools

Tool	Description	Use Case
search	AI Web Search. Searches Google and summarizes results using Gemini. Returns sources.	"How do I center a div in Tailwind 4?" or "Latest features in Python 3.13"
analyze_url	Deep Page Reader. Ingests the content of a specific URL (HTML/PDF/Text) into context.	"Read this documentation page and explain the implementation details."

Available Prompts

Pre-configured prompts to make common tasks easier:

Prompt	Description	Arguments
web-search	Search the web for up-to-date information	topic (required)
analyze-documentation	Analyze and summarize technical documentation	url (required), focus (optional)
research-topic	Comprehensive research with multiple sources	topic (required)
compare-technologies	Compare technologies/frameworks/tools	technologies (required), criteria (optional)

Available Resources

Resource	URI	Description
Server Information	gemini://server/info	Details about the server version and capabilities
Server Capabilities	gemini://server/capabilities	JSON of all features, tools, and limits

---

Quick Start

1. Clone the repository

git clone https://github.com/nav9v/gemini-search-mcp.git
cd gemini-mcp-server

2. Set up the Python environment

python -m venv .venv
# Activate virtual environment
# Windows:
.venv\Scripts\Activate.ps1
# Mac/Linux:
source .venv/bin/activate

pip install -r requirements.txt

💡 PowerShell execution policy error?

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3. Get your Free API Key

1. Go to Google AI Studio.
2. Create a free API key (no credit card needed).
3. Create a .env file in the root directory:

GEMINI_API_KEY=your_actual_api_key_here
GEMINI_MODEL=gemini-2.5-flash

4. Add to VS Code

Edit your MCP config file:

• Windows: %APPDATA%\Code\User\mcp.json
• Mac/Linux: ~/Library/Application Support/Code/User/mcp.json

Option 1: Using working directory (Recommended)

{
  "mcpServers": {
    "gemini-search": {
      "command": "python",
      "args": ["gemini_search_mcp.py"],
      "cwd": "C:/absolute/path/to/gemini-search-mcp",
      "env": {
        "PYTHONPATH": "C:/absolute/path/to/gemini-search-mcp"
      }
    }
  }
}

Option 2: Using virtual environment

{
  "mcpServers": {
    "gemini-search": {
      "command": "C:/absolute/path/to/.venv/Scripts/python.exe",
      "args": ["C:/absolute/path/to/gemini_search_mcp.py"]
    }
  }
}

Note:

• Replace C:/absolute/path/to/ with the full path to your cloned folder
• Use forward slashes (/) or double backslashes (\\) in paths
• The server loads .env automatically, so you don't need the env block if using .env
• See mcp.json.example for a template

5. Reload VS Code

Press Ctrl+Shift+P → Developer: Reload Window.

---

💬 Usage Examples

Using Tools Directly

Open Copilot Chat (or your MCP client) and ask:

• "Search for the latest Next.js 15 breaking changes." (Triggers search)
• "Analyze this page: https://docs.python.org/3/whatsnew/3.13.html" (Triggers analyze_url)
• "What are the best open source alternatives to Vercel in 2026?"
• "Read the docs at https://fastapi.tiangolo.com/ and explain how to use dependency injection."

Using Prompts (Recommended)

Prompts provide structured templates for common tasks:

• Web Search: Use the web-search prompt with a topic
• Documentation Analysis: Use the analyze-documentation prompt with a URL
• Research: Use the research-topic prompt for comprehensive research
• Comparison: Use the compare-technologies prompt to compare tools/frameworks

Example in VS Code Copilot:

@gemini-search #web-search topic="Python async best practices 2026"

---

Configuration

All config is via .env in the project root:

Variable	Default	Description
GEMINI_API_KEY	(required)	Google AI Studio API key
GEMINI_MODEL	gemini-2.5-flash	Gemini model name

Supported Models

Model	Status	Cost	Best For
gemini-2.5-flash	✅ Stable	Free	General Use — fast, free tier, accurate.
gemini-2.5-flash-lite	✅ Stable	Free	Ultra-fast simple queries.
gemini-2.5-pro	✅ Stable	Paid*	Complex reasoning & research planning.
gemini-2.0-flash-thinking	🧪 Preview	Free	Deep reasoning tasks.

*Paid after free tier limits.

---

💰 Pricing

Completely Free.

1. Google AI Studio API: Free tier includes 1,500 requests per day.
2. This Software: Open source (MIT).

No credit card required. Perfect for individual developers, students, and prototypers.

---

🆚 Comparison

Feature	This Server	Brave Search MCP	Tavily / Serper	Perplexity
Engine	Google (Grounding)	Brave Index	Tavily Index	Perplexity
Full Page Read	✅ Yes (huge context)	❌ No	❌ No	❌ No
Citations	✅ Inline Links	✅	✅	✅
Prompts	✅ 4 Pre-configured	❌ No	❌ No	❌ No
Resources	✅ Server Info	❌ No	❌ No	N/A
Cost	🆓 Free (1.5k/day)	🆓 Limited	🆓 Limited	💸 $20/mo
Privacy	🔒 Local Client*	🔒 Local Client	☁️ API	☁️ API

*Runs locally, sends queries to Google Gemini API.

---

🛠 Troubleshooting

Test Server Manually

Before configuring VS Code, test the server directly:

# Activate virtual environment first
.venv\Scripts\Activate.ps1

# Run the server
python gemini_search_mcp.py

The server should start without errors. Press Ctrl+C to stop.

Verify Installation

1. Open VS Code Output panel (Ctrl+Shift+U).
2. Select "MCP Review" or "Github Copilot Default" from the dropdown.
3. Look for gemini-search in the logs.
4. Check for any error messages or connection issues.

"GEMINI_API_KEY is not set"

• Ensure .env is in the same folder as the script.
• Verify the path in mcp.json is absolute: c:/Users/.../gemini-search-mcp/gemini_search_mcp.py.
• Check that .env contains a valid API key without quotes or spaces.
• Test locally: python -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.getenv('GEMINI_API_KEY'))"

Server Not Appearing in VS Code

1. Verify mcp.json syntax is valid (use a JSON validator).
2. Ensure paths use forward slashes or double backslashes.
3. Check that Python is accessible from the command line: python --version
4. Try using absolute path to Python executable in virtual environment.
5. Reload VS Code window: Ctrl+Shift+P → Developer: Reload Window

Validation Failed

If the MCP server validation fails:

1. Ensure all dependencies are installed: pip install -r requirements.txt
2. Check that the google-genai package is properly installed: pip show google-genai
3. Verify your API key is valid at Google AI Studio
4. Test the server manually before adding to VS Code
5. Check that prompts and resources are properly defined (this MCP server includes them)

---

Contributing

Pull requests are welcome! Please format code with black and ensure strict typing.

License

MIT © 2026 Navneet Sharma

---

Keywords

VS Code Extension, Model Context Protocol, MCP Server, Gemini API, Google Search Grounding, RAG, Retrieval Augmented Generation, Perplexity Alternative, Open Source AI, Copilot Tools, Cline, Roo Code, AI Search, Python, Deep Research.