Gemini Deep Researcher MCP 🔍

An advanced Model Context Protocol (MCP) server that fully automates Google Gemini's Deep Research capabilities. Connect any compatible LLM (Claude, Cursor, Antigravity) directly to Gemini's background research engine without requiring any paid API keys.

🚀 Key Features

• Hybrid Engine (DOM + Network Interception): Uses Playwright to drive the UI securely while intercepting Gemini's internal APIs (StreamGenerate and batchexecute) for 100% reliable state tracking.
• Stealth Automation: Built-in human-like typing, random delays, and bezier curve mouse movements to ensure Google never flags the session as a bot.
• File Uploads: Pass local file paths directly into the MCP tool to automatically upload them before the prompt is sent (up to 99MB).
• Asynchronous Lifecycle: Non-blocking tool execution allows your AI agent to trigger research, go do other things, and check back later.
• Direct Extraction: Grabs the massive final Markdown output directly from the chat and pipes it straight back to your agent context.

🛠️ Quick Installation (Recommended)

The easiest way to use this server is through npx, which avoids downloading source code or compiling anything. You only need to have Node.js installed on your computer.

Here is how to configure it in your favorite AI client:

1. Cursor IDE / Windsurf

Both Cursor and Windsurf support MCP natively:

1. Open settings and look for the MCP section.
2. Click + Add New MCP Server.
3. Fill in the details:
   • Name: gemini-deep-research
   • Type: command
   • Command: npx -y gemini-deep-researcher-mcp

2. Claude Desktop

1. Open your Claude configuration file. On Windows, it is normally located at: C:\Users\<YourUser>\AppData\Roaming\Claude\claude_desktop_config.json (On Mac: ~/Library/Application Support/Claude/claude_desktop_config.json)
2. Add this code inside the file:

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "npx",
      "args": ["-y", "gemini-deep-researcher-mcp"]
    }
  }
}

3. Claude CLI / Claude Code

If you use the Claude command line, simply run:

claude mcp add gemini-deep-research npx -y gemini-deep-researcher-mcp

4. Antigravity / Codex

Add the server in your mcp_config.json file:

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "npx",
      "args": ["-y", "gemini-deep-researcher-mcp"]
    }
  }
}

⚠️ First Run Note: The very first time the server runs, a Chrome window will appear. You must log in to your Google account manually. Your session will be saved persistently for all future automated runs!

💻 Manual Installation (For Developers)

If you prefer to download the source code and run it locally:

1. Clone this repository: git clone https://github.com/voftec/gemini-deep-researcher-mcp.git
2. Install dependencies: npm install
3. Compile the code: npm run build
4. Test the script standalone: node test.js
5. In your MCP client, instead of npx, use the local command: node /path/to/your/folder/dist/index.js

🧰 Available Tools

The server exposes 4 specialized tools orchestrated to simulate a fully autonomous research lifecycle:

1. start_deep_research: Begins the deep research and instantly returns control. Accepts a prompt, model, and files array.
2. check_research_status: Polls the network interceptor state without blocking. Returns running, waiting_for_confirmation, or completed.
3. answer_confirmation: If Gemini asks a clarification question before starting, use this to reply and unblock the research.
4. get_research_result: Once completed, this returns the final, beautiful Markdown generated by Deep Research directly into the agent's context.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.