Langgraph Deep Search

This MCP server lets you perform comprehensive LangGraph-driven deep searches using Gemini-native capabilities, manage multi-step research workflows, and automatically surface sources via grounding metadata. It is designed to integrate with MCP hosts and external applications to deliver thorough results and traceable citations.

How to use

You connect this server to an MCP host (such as Claude Desktop) and issue natural language research commands. Use deep_search for thorough, multi-iteration investigations, or quick_search for fast lookups. The server uses LangGraph for state management and Gemini-native search to deliver high-quality results with automatically grounded sources.

Practical usage patterns you can try after connecting your MCP host:

Deep search example: you want a comprehensive comparison of a topic. Ask for an in-depth, multi-iteration analysis with citations and sources included automatically.

How to install

Prerequisites: Python 3.10+ and uvx or uv installed on your system.

# 1. Clone the project
git clone https://github.com/RyotaOzawa0/langgraph-deepsearch-mcp.git
cd deep-search-mcp-server

# 2. Install dependencies (recommended using uvx)
# Option A: using uvx (preferred)
# 3. Run the MCP server using uvx (see the exact command below in the start section)

Alternative manual setup for environments without uvx is shown here. You will later start the server with Python directly or via uv run.

# 1. Clone the repository
git clone <repository-url>
cd deep-search-mcp-server

# 2. Install dependencies
uv sync
uv pip install -e .

# 3. Copy and configure environment keys
cp .env.example .env
# Edit .env to set GEMINI_API_KEY

# 4. Start tests (or run in normal mode)
uv run python gemini_server.py

MCP start options and environment variables

There are two explicit local start methods you can use to run the MCP server. Each method provides a complete runtime command and includes the required Gemini API key via environment variables.

{
  "mcpServers": {
    "langgraph_ds_uvx": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", ".", "langgraph-deep-search"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    },
    "langgraph_ds_uvrun": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/deep-search-mcp-server", "python", "gemini_server.py"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}

Notes on configuration and startup

Provide your Gemini API key to enable native Gemini search features and grounding of sources. For development or debugging, you can run in development mode to get verbose logs that help identify configuration issues.

Troubleshooting

Common issues include missing modules, uninitialized agents, and errors starting the server. Ensure dependencies are installed with the project’s setup commands and that the GEMINI_API_KEY is set in your environment.

# Reinstall dependencies if needed
uv sync
uv run python gemini_server.py

# If running via uvx or uv, ensure keys are exported
export GEMINI_API_KEY=your_gemini_api_key_here

License and contribution

This project is released under the MIT License. Contributions follow standard forking, feature branching, and pull requests.

Available tools

deep_search

Performs a comprehensive, multi-iteration investigation on a given topic, aggregating results across iterations and grounding sources.

quick_search

Executes a single, fast search to retrieve results quickly without iterative exploration.

get_search_tools

Checks and reports the currently available search tools and their status.