Gemini Deep Research MCP

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

Quick Start

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

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

Requires: uv for uvx method

One-Click Install

| IDE | Install | |-----|---------| | Cursor | | | VS Code | | | VS Code Insiders | |

Note: After clicking, replace your-api-key with your Gemini API key. VS Code requires version 1.101+.

Installation Methods

Using uvx (Recommended)

Requires uv.

uvx gemini-deep-research-mcp

{
  "servers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

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

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Add to ~/.codex/config.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"

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "uvx",
      "args": ["gemini-deep-research-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Add to your Antigravity mcp_config.json:

{
  "gemini-deep-research": {
    "command": "uvx",
    "args": ["gemini-deep-research-mcp"],
    "env": {
      "GEMINI_API_KEY": "your-api-key"
    }
  }
}

Using pip

pip install gemini-deep-research-mcp

{
  "servers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

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

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Add to ~/.codex/config.toml:

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

[mcp_servers.gemini-deep-research.env]
GEMINI_API_KEY = "your-api-key"

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gemini-deep-research": {
      "command": "gemini-deep-research-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Add to your Antigravity mcp_config.json:

{
  "gemini-deep-research": {
    "command": "gemini-deep-research-mcp",
    "env": {
      "GEMINI_API_KEY": "your-api-key"
    }
  }
}

Prerequisites

# 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"

Tools

1. start_deep_research

Initiates a deep, multi-step web research job in the background using Google's Deep Research Agent. Returns a job_id, which you can use to check the status of completion using check_deep_research(job_id=...).

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | prompt | string | ✓ | — | Your comprehensive research question or topic |

| Output | Description | |--------|-------------| | job_id | Unique tracking ID for the research job | | status | Initial job state (e.g. in_progress) |

2. check_deep_research

Checks the status of a Deep Research job using its job_id and returns the complete report once finished.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | job_id | string | ✓ | — | The research tracking ID from start_deep_research | | include_citations | boolean | | true | Include source URLs in the report |

| Output | Description | |--------|-------------| | job_id | The tracking ID of the research job | | status | Exact current job state (in_progress, completed, failed, or cancelled) | | report_text | Synthesized markdown research report (when completed) | | uptime | Elapsed time while the job is in progress, when available | | error | Failure details, when the API provides them |

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GEMINI_API_KEY | ✓ | — | Your Gemini API key | | GEMINI_DEEP_RESEARCH_AGENT | | deep-research-preview-04-2026 | Deep Research agent to use. Set to deep-research-max-preview-04-2026 for maximum thoroughness, or deep-research-preview-04-2026 for standard speed. |

Links

• 📦 npm Package
• 🔧 GitHub Repository
• 🔑 Get Gemini API Key

License

MIT