Deep Research

You run an MCP server that orchestrates deep research queries using Gemini 2.5 Flash, with optional grounding tools. This server can be started locally or inspected interactively, and it exposes a programmable interface for MCP clients to request iterative, structured research reports.

How to use

Use this MCP server with any MCP client to perform iterative, deep research tasks. Start a local MCP server and then invoke the deep research tool from your client with a research query, optional depth and breadth, and any existing learnings to guide the session. The server will query sources, extract learnings, refine directions, and finally assemble a structured Markdown report.

How to install

Prerequisites: Node.js v22.x and npm installed on your system.

1. Clone the project and install dependencies.

2. Install dependencies.

3. Create a local environment file with the required Gemini API key and configuration.

4. Build the project.

5. Start the MCP server using one of the supported commands.

Configuration

The server relies on environment variables to configure the Gemini model, tokens, concurrency, and tool usage. Create a local environment file and pass it to the server on startup.

Required environment variables include your Gemini API key and model settings. Optional tool toggles enable Google Search Grounding, Code Execution, and Functions.

Usage patterns with an MCP client

• Start the MCP server locally and connect from a client that supports MCP tool invocation. - Use the client to pass a query, set depth and breadth (1–5), and supply any existing learnings to guide the session. - Retrieve and review the final Markdown report along with its sources.

Example startup commands

# Start as a standard MCP server
node --env-file .env.local dist/mcp-server.js

# Start with inspector support for interactive debugging
npx @modelcontextprotocol/inspector node --env-file .env.local dist/mcp-server.js

Quickstart

1. Ensure Node.js v22.x is installed. 2) Clone the project. 3) Install dependencies. 4) Create a local environment file (see example below). 5) Build the project. 6) Run the server using one of the startup commands above.

Example Output

The final report is a structured Markdown document including Abstract, Table of Contents, Introduction, Body, Methodology, Limitations, Key Learnings, and References.

Troubleshooting

Missing API key: Ensure GEMINI_API_KEY is set in the environment file and used when starting the server. If grounding or tools are not active, verify the corresponding ENABLE_GEMINI_* flags. If outputs are too long, adjust depth/breadth or max output tokens. If there are schema or parsing issues, rerun with adjusted prompts or smaller chunks.

Notes on security and best practices

Keep your Gemini API key secure and avoid leaking it in logs. Use controlled concurrency to balance speed and rate limits. Validate outputs and ensure that generated sources are properly cited.

Available tools

Google Search Grounding

Tool that grounds queries with Google SERP data to improve relevance and grounding of research results.

Code Execution

Tool that allows running code snippets to validate findings or reproduce results.

Functions

Tooling to invoke structured actions or endpoints as part of the research workflow.