Metadata-Version: 2.4
Name: gemini-deep-research-mcp
Version: 0.1.3
Summary: MCP server exposing Gemini Deep Research (Interactions API) tools
Author-email: Ayush <ayusin439@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bharatvansh/gemini-deep-research-mcp
Project-URL: Repository, https://github.com/bharatvansh/gemini-deep-research-mcp
Project-URL: Issues, https://github.com/bharatvansh/gemini-deep-research-mcp/issues
Keywords: mcp,gemini,deep-research,ai,google,model-context-protocol,research,agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.2.0
Requires-Dist: google-genai>=0.6.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"

# Gemini Deep Research MCP

[![PyPI version](https://img.shields.io/pypi/v/gemini-deep-research-mcp)](https://pypi.org/project/gemini-deep-research-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An MCP server that exposes Gemini's **Deep Research Agent** for comprehensive web research.

## Quick Start

```bash
# Recommended (zero-install)
uvx gemini-deep-research-mcp

# Or install globally
pip install gemini-deep-research-mcp
gemini-deep-research-mcp
```

> **Requires:** [uv](https://docs.astral.sh/uv/) for uvx method

## One-Click Install

| IDE | Install |
|-----|---------|
| **Cursor** | [![Install in Cursor](https://img.shields.io/badge/Install-Cursor-blue?logo=cursor)](https://cursor.com/en/install-mcp?name=gemini-deep-research&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJnZW1pbmktZGVlcC1yZXNlYXJjaC1tY3AiXSwiZW52Ijp7IkdFTUlOSV9BUElfS0VZIjoieW91ci1hcGkta2V5In19) |
| **VS Code** | [![Install in VS Code](https://img.shields.io/badge/Install-VS%20Code-007ACC?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=gemini-deep-research&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22gemini-deep-research-mcp%22%5D%2C%22env%22%3A%7B%22GEMINI_API_KEY%22%3A%22your-api-key%22%7D%7D) |
| **VS Code Insiders** | [![Install in VS Code Insiders](https://img.shields.io/badge/Install-VS%20Code%20Insiders-24bfa5?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=gemini-deep-research&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22gemini-deep-research-mcp%22%5D%2C%22env%22%3A%7B%22GEMINI_API_KEY%22%3A%22your-api-key%22%7D%7D&quality=insiders) |

> **Note:** After clicking, replace `your-api-key` with your [Gemini API key](https://aistudio.google.com/apikey). VS Code requires version 1.101+.

---

## Installation Methods

### Using uvx (Recommended)

Requires [uv](https://docs.astral.sh/uv/).

```bash
uvx gemini-deep-research-mcp
```

<details>
<summary><strong>VS Code config</strong></summary>

```json
{
  "servers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Claude Desktop config</strong></summary>

```json
{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Windsurf config</strong></summary>

Add to `~/.codeium/windsurf/mcp_config.json` (macOS/Linux) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows):

```json
{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Cline config</strong></summary>

```json
{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Claude Code config</strong></summary>

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Codex config</strong></summary>

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.gemini-deep-research]
command = "uvx"
args = ["gemini-deep-research-mcp"]

[mcp_servers.gemini-deep-research.env]
GEMINI_API_KEY = "your-api-key"
```
</details>

<details>
<summary><strong>Cursor config</strong></summary>

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Antigravity config</strong></summary>

Add to your Antigravity `mcp_config.json`:

```json
{
  "gemini-deep-research": {
    "command": "uvx",
    "args": ["gemini-deep-research-mcp"],
    "env": {
      "GEMINI_API_KEY": "your-api-key"
    }
  }
}
```
</details>

---

### Using pip

```bash
pip install gemini-deep-research-mcp
```

<details>
<summary><strong>VS Code config</strong></summary>

```json
{
  "servers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Claude Desktop config</strong></summary>

```json
{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Windsurf config</strong></summary>

Add to `~/.codeium/windsurf/mcp_config.json` (macOS/Linux) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows):

```json
{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Cline config</strong></summary>

```json
{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Claude Code config</strong></summary>

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Codex config</strong></summary>

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.gemini-deep-research]
command = "gemini-deep-research-mcp"

[mcp_servers.gemini-deep-research.env]
GEMINI_API_KEY = "your-api-key"
```
</details>

<details>
<summary><strong>Cursor config</strong></summary>

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Antigravity config</strong></summary>

Add to your Antigravity `mcp_config.json`:

```json
{
  "gemini-deep-research": {
    "command": "gemini-deep-research-mcp",
    "env": {
      "GEMINI_API_KEY": "your-api-key"
    }
  }
}
```
</details>

---

## Prerequisites

<details>
<summary><strong>Install uv (required for uvx method)</strong></summary>

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
</details>

---

## Tool: `gemini_deep_research`

Conducts comprehensive web research using Gemini's Deep Research Agent. Blocks until research completes (typically 10-20 minutes).

**When to use:**
- Complex topics requiring multi-source analysis
- Synthesized information from the web
- Fact-checking and cross-referencing

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | ✓ | — | Your research question or topic |
| `include_citations` | boolean | | `true` | Include resolved source URLs |

| Output | Description |
|--------|-------------|
| `status` | `completed`, `failed`, or `cancelled` |
| `report_text` | Synthesized research report |

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GEMINI_API_KEY` | ✓ | — | Your [Gemini API key](https://aistudio.google.com/apikey) |
| `GEMINI_DEEP_RESEARCH_AGENT` | | `deep-research-pro-preview-12-2025` | Model to use |

## Links

- 📦 [npm Package](https://www.npmjs.com/package/@bharatvansh/gemini-deep-research-mcp)
- 🔧 [GitHub Repository](https://github.com/bharatvansh/gemini-deep-research-mcp)
- 🔑 [Get Gemini API Key](https://aistudio.google.com/apikey)

## License

MIT
