gemini-deep-researcher-mcp

# Gemini Deep Researcher MCP 🔍 [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](https://opensource.org/licenses/MIT) 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](https://nodejs.org/) 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: ```json { "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: ```bash claude mcp add gemini-deep-research npx -y gemini-deep-researcher-mcp ``` ### 4. Antigravity / Codex Add the server in your `mcp_config.json` file: ```json { "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](LICENSE) file for details.