Deep Research MCP Server

Your AI-Powered Research Assistant. Conduct iterative, deep research using Google Gemini 2.5 Flash with Google Search Grounding and URL context. No web-scraping dependency is required.

Table of Contents

• Features
• Why This Project
• Workflow Diagram
• Persona Agents
• How It Works
• Project Structure
• Requirements
• Setup
• Usage
  • As MCP Tool
  • Standalone CLI Usage
  • MCP Inspector Testing
• Configuration
• Quickstart
• Example Output
• Support
• Contributing
• Roadmap
• License

The goal of this project is to provide the simplest yet most effective implementation of a deep research agent. It's designed to be easily understood, modified, and extended, aiming for a codebase under 500 lines of code (LoC).

Key Features:

• MCP Integration: Runs as a Model Context Protocol (MCP) server/tool for seamless agent integration.
• Gemini 2.5 Flash Pipeline: Long-context reasoning, structured JSON outputs, and tool use (Google Search Grounding, Code Execution, Functions) via env flags.
• Iterative Deep Dive: Query refinement + result analysis with learned context carried forward.
• Depth & Breadth Control: Tune exploration scope precisely.
• Semantic/Recursive Splitting: Token-aware chunking for robust summarization and analysis.
• Batching + Caching: Concurrency-limited batched model calls with LRU caches across prompts/results.
• Professional Reports: Generates structured Markdown (Abstract, ToC, Intro, Body, Methodology, Limitations, Key Learnings, References).

Why This Project

• Gemini-first, modern pipeline: Built around Gemini 2.5 Flash with optional tools (Search Grounding, Code Execution, Functions).
• Minimal, understandable core: Plain TypeScript; easy to audit and extend.
• Deterministic outputs: Zod-validated JSON and consistent report scaffolding.
• Agent-ready: Clean MCP server entry; works with Inspector and MCP-aware clients.

Workflow Diagram

flowchart TB
    subgraph Input
        Q[User Query]
        B[Breadth Parameter]
        D[Depth Parameter]
    end

    DR[Deep Research] -->
    SQ[SERP Queries] -->
    PR[Process Results]

    subgraph Results[Results]
        direction TB
        NL((Learnings))
        ND((Directions))
    end

    PR --> NL
    PR --> ND

    DP{depth > 0?}

    RD["Next Direction:
    - Prior Goals
    - New Questions
    - Learnings"]

    MR[Markdown Report]

    %% Main Flow
    Q & B & D --> DR

    %% Results to Decision
    NL & ND --> DP

    %% Circular Flow
    DP -->|Yes| RD
    RD -->|New Context| DR

    %% Final Output
    DP -->|No| MR

    %% Styling
    classDef input fill:#7bed9f,stroke:#2ed573,color:black
    classDef process fill:#70a1ff,stroke:#1e90ff,color:black
    classDef recursive fill:#ffa502,stroke:#ff7f50,color:black
    classDef output fill:#ff4757,stroke:#ff6b81,color:black
    classDef results fill:#a8e6cf,stroke:#3b7a57,color:black

    class Q,B,D input
    class DR,SQ

... [View full README on GitHub](https://github.com/ssdeanx/deep-research-mcp-server#readme)