epilande/gemini-grounding

An MCP (Model Context Protocol) server that provides real-time information access using Google Gemini's grounding capabilities. This server enables MCP-compatible clients to search for current information, developer resources, documentation, and Reddit discussions using Gemini's built-in Google Search grounding.

❓ Why?

When working with AI assistants like Claude Code, you often need current information and community insights that are beyond the model's knowledge cutoff. Claude Code refuses to search Reddit and have limitations on accessing real-time information.

This MCP server bypasses these limitations by leveraging Gemini's grounding capabilities, which can search the web and other sources to provide current information, code examples, discussions, and community insights directly within your AI workflow.

✨ Features

• 🔍 Real-time Search: Access current information through Gemini's Google Search grounding
• 👨‍💻 Developer-Focused: Tools for searching code examples, documentation, and troubleshooting
• 💬 Reddit Integration: Search Reddit discussions and community insights
• 📚 Automatic Citations: Source links and attribution provided automatically by Gemini
• 🔗 Multi-Source Synthesis: Combines information from multiple web sources
• 🎯 Context-Aware: Tailored search results based on programming language and framework
• ✅ Fact Verification: Built-in fact-checking and accuracy validation

📦 Installation

Prerequisites

• Node.js 18+
• Google Gemini API key from Google AI Studio

Option 1: Use with npx

npx gemini-grounding

Option 2: Build from Source

git clone https://github.com/epilande/gemini-grounding.git
cd gemini-grounding
pnpm install
pnpm build

Getting a Gemini API Key

1. Visit Google AI Studio
2. Create or select a project
3. Generate an API key
4. Add the key to your .env file

🎮 Usage

This server works with any MCP-compatible client.

Claude Code

Add this server to your Claude Code MCP configuration using the claude mcp add command:

claude mcp add gemini-grounding -e GEMINI_API_KEY="${GEMINI_API_KEY}" -- npx -y gemini-grounding

Or manually add to your configuration:

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "npx",
      "args": ["-y", "gemini-grounding"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}

Verification

After adding to your configuration:

1. Restart your MCP client (e.g., Claude Code)
2. Open a new conversation
3. Look for Gemini grounding tools in the tool picker
4. Test with queries like:
   • "Why is neovim the best editor? Search reddit"
   • "What are the new Go lang features?"
   • "Latest docs for React hooks"
   • "What are useEffect dependency array best practices"

🛠️ Tools

search_with_grounding

General purpose search with Gemini grounding capabilities.

Parameters:

• query (required): Search query
• context (optional): Development context or additional information
• focus (optional): Focus area - "general", "code", "documentation", or "troubleshooting"

search_developer_resources

Specialized search for developer resources and documentation.

Parameters:

• query (required): Technical query
• language (optional): Programming language (e.g., JavaScript, Python, Rust)
• framework (optional): Framework or library (e.g., React, Express, Django)

search_documentation

Search for official documentation and API references.

Parameters:

• query (required): Documentation query
• technology (optional): Technology, framework, or tool name

search_reddit

Search Reddit discussions and community insights.

Parameters:

• query (required): Search query for Reddit content
• subreddit (optional): Specific subreddit to search (e.g., "programming", "reactjs")

🏗️ Architecture

┌─────────────────────────────────────┐
│        MCP-Compatible Client        │
│  • Claude Code, Cursor, etc.        │
│  • File editing & bug fixing        │
│  • Codebase analysis                │
│  • Development workflows            │
└─────────────┬───────────────────────┘
              │ MCP Integration
┌─────────────▼───────────────────────┐
│   Node.js Grounding Agent Service   │
│  • Query routing & analysis         │
│  • Context management               │
│  • Response formatting              │
└─────────────┬───────────────────────┘
              │ Single API Call
┌─────────────▼───────────────────────┐
│      Gemini 2.5 Flash               │
│  • Google Search grounding          │
│  • Real-time information access     │
│  • Automatic source citation        │
│  • Multi-source synthesis           │
└─────────────────────────────────────┘

🔧 Development

# Development mode
pnpm dev

# Build
pnpm build

# Production
pnpm start

🐛 Troubleshooting

Common Issues

Server fails to start with "GEMINI_API_KEY environment variable is required"

• Ensure you've created a .env file with your API key
• Or pass the API key in the MCP configuration env section
• Verify your API key is valid at Google AI Studio

Tools don't appear in your MCP client

• Check that the file path in your configuration is absolute and correct
• Restart your MCP client after making configuration changes
• Verify the server builds successfully with pnpm build
• Check your client's logs for any error messages

"Module not found" errors

• Run pnpm install to ensure all dependencies are installed
• Make sure you're using Node.js 18 or later
• Try deleting node_modules and running pnpm install again

Search requests fail or timeout

• Verify your Gemini API key has quota remaining
• Check your internet connection
• Ensure the Gemini API service is accessible from your network