Deep Research Mcp

Deep Research MCP

[](https://github.com/pminervini/deep-research-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io/) [](https://github.com/pminervini/deep-research-mcp#claude-code-integration) [](https://platform.openai.com/) [](https://ai.google.dev/)

A Python-based agent that integrates research providers with Claude Code through the Model Context Protocol (MCP). It supports OpenAI (Responses API with web search and code interpreter, or Chat Completions API for broad provider compatibility), Gemini Deep Research via the Interactions API, Allen AI's DR-Tulu research agent, and the open-source Open Deep Research stack (based on smolagents).

Prerequisites

• Python 3.11+
• uv installed
• One of:
• OpenAI API access (Responses API models, e.g., o4-mini-deep-research-2025-06-26)
• Gemini API access with the Interactions API / Deep Research agent enabled
• DR-Tulu service running locally or remotely (see [DR-Tulu setup](#dr-tulu-provider-example))
• Open Deep Research dependencies (installed via uv sync --extra open-deep-research)
• Claude Code, or any other assistant supporting MCP integration

Installation

Recommended setup (resolves the latest compatible versions):

# Install runtime dependencies + project in editable mode
uv sync --upgrade

# Development tooling (pytest, black, pylint, mypy, pre-commit)
uv sync --upgrade --extra dev

# Enable the pre-commit hook so black runs automatically before each commit
uv run pre-commit install

# Optional docs tooling
uv sync --upgrade --extra docs

# Optional Open Deep Research provider dependencies
uv sync --upgrade --extra open-deep-research

Compatibility setup (pip-based):

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

Code Layout

• src/deep_research_mcp/agent.py: orchestration layer; owns clarification, instruction building, callbacks, and delegates provider work to backends
• src/deep_research_mcp/backends/: provider-specific implementations for OpenAI, Gemini, DR-Tulu, and Open Deep Research
• src/deep_research_mcp/mcp_server.py: FastMCP server and tool entrypoints
• src/deep_research_mcp/clarification.py: clarification agents, sessions, and enrichment flow
• src/deep_research_mcp/prompts/: YAML prompt templates used by clarification and instruction building
• cli/deep-research-cli.py: unified CLI for agent mode, MCP client mode, and configuration viewing
• cli/deep-research-tui.py: interactive full-screen terminal UI for clarification, research, status checks, and saving output to disk
• tests/: pytest suite covering configuration, MCP integration, prompts, results, and clarification flows

Configuration

Configuration File

Create a ~/.deep_research file in your home directory using TOML format.

Library note: ResearchConfig.load() explicitly reads this file and applies environment variable overrides. ResearchConfig.from_env() reads environment variables only.

Common settings:

[research]                                  # Core Deep Research functionality
provider = "openai"                         # Available options: "openai", "dr-tulu", "gemini", "open-deep-research" -- defaults to "openai"
api_style = "responses"                     # Only applies to provider="openai"; use "chat_completions" for Perplexity, Groq, Ollama, etc.
model = "o4-mini-deep-research-2025-06-26"  # OpenAI: model identifier; Dr Tulu: logical provider id; Gemini: agent id; ODR: LiteLLM model identifier
api_key = "your-api-key"                    # API key, optional
base_url = "https://api.openai.com/v1"      # OpenAI: OpenAI-compatible endpoint; Dr Tulu: service base URL; Gemini: https://generativelanguage.googleapis.com; ODR: LiteLLM-compatible endpoint

# Task behavior
timeout = 1800
poll_interval = 30
cancel_on_timeout = false  # When true, cancel the provider task if it exceeds timeout. Default false: the task keeps running and the result can be recovered with research_status

# Largely based on https://cookbook.openai.com/examples/deep_research_api/introduction_to_deep_research_api_agents
[clarification]                                       # Optional query clarification component
enable = true
triage_model = "gpt-5-mini"
clarifier_model = "gpt-5-mini"
instruction_builder_model = "gpt-5-mini"
api_key = "YOUR_OPENAI_API_KEY"         # Optional, overrides api_key
base_url = "https://api.openai.com/v1"  # Optional, overrides base_url

[logging]
level = "INFO"

Note on precedence: [research] api_key and base_url map to the RESEARCH_API_KEY and RESEARCH_BASE_URL settings, which apply to every provider. If you switch provider via an environment override (e.g. RESEARCH_PROVIDER=openai) while the file is configured for another provider, also override RESEARCH_API_KEY and RESEARCH_BASE_URL, otherwise the file's key and endpoint are used.

OpenAI provider example:

[research]
provider = "openai"
model = "o4-mini-deep-research-2025-06-26"  # OpenAI model
api_key = "YOUR_OPENAI_API_KEY"             # Defaults to OPENAI_API_KEY
base_url = "https://api.openai.com/v1"      # OpenAI-compatible endpoint
timeout = 1800
poll_interval = 30

Gemini Deep Research provider example:

[research]
provider = "gemini"
model = "deep-research-preview-04-2026"     # Gemini Deep Research agent id
api_key = "YOUR_GEMINI_API_KEY"                # Defaults to GEMINI_API_KEY or GOOGLE_API_KEY
base_url = "https://generativelanguage.googleapis.com"
timeout = 1800
poll_interval = 30

Dr Tulu provider example:

[research]
provider = "dr-tulu"
model = "dr-tulu"                   # Logical provider model id; currently informational
base_url = "http://localhost:8080/"   # Dr Tulu service base URL; the backend calls /chat
api_key = ""                        # Optional; defaults to RESEARCH_API_KEY / DR_TULU_API_KEY if set
timeout = 1800
poll_interval = 30

Running Dr Tulu locally:

1. Clone and configure dr-tulu separately.
2. In dr-tulu/agent/.env, set at least:

• SERPER_API_KEY
• JINA_API_KEY
• S2_API_KEY (optional but recommended)

1. Start the DR-Tulu model server:

cd /path/to/dr-tulu/agent
conda run -n vllm bash -lc '
  CUDA_VISIBLE_DEVICES=0 \
  vllm serve rl-research/DR-Tulu-8B \
    --port 30001 \
    --dtype auto \
    --max-model-len 16384 \
    --gpu-memory-utilization 0.60 \
    --enforce-eager
'

1. Start the Dr Tulu MCP backend:

cd /path/to/dr-tulu/agent
conda run -n vllm python -m dr_agent.mcp_backend.main --port 8000

1. Start the Dr Tulu app service:

cd /path/to/dr-tulu/agent
conda run -n vllm python workflows/auto_search_sft.py serve \
  --port 8080 \
  --config workflows/auto_search_sft.yaml \
  --config-overrides "search_agent_max_tokens=12000,browse_agent_max_tokens=12000"

1. Point deep-research-mcp at that service:

[research]
provider = "dr-tulu"
base_url = "http://localhost:8080/"
timeout = 1800

The dr-tulu backend calls POST {base_url}/chat, so if you front Dr Tulu behind a different host, port, or reverse proxy, update base_url accordingly.

Perplexity (via Sonar Deep Research and Perplexity's OpenAI-compatible endpoint) provider example:

[research]
provider = "openai"
api_style = "chat_completions"              # Required for Perplexity (no Responses API)
model = "sonar-deep-research"               # Perplexity's Sonar Deep Research
api_key = "ppl-..."                         # Defaults to OPENAI_API_KEY
base_url = "https://api.perplexity.ai"      # Perplexity's OpenAI-compatible endpoint
timeout = 1800

Open Deep Research provider example:

[research]
provider = "open-deep-research"
model = "openai/qwen/qwen3-coder-30b"  # LiteLLM-compatible model id
base_url = "http://localhost:1234/v1"  # LiteLLM-compatible endpoint (local or remote)
api_key = ""                           # Optional if endpoint requires it
timeout = 1800

Ollama (local) provider example:

[research]
provider = "openai"
api_style = "chat_completions"
model = "llama3.1"                     # Any model available in your Ollama instance
base_url = "http://localhost:11434/v1" # Ollama's OpenAI-compatible endpoint
api_key = ""                           # Not required for local Ollama
timeout = 600

llama-server (local llama.cpp server) provider example:

[research]
provider = "openai"
api_style = "chat_completions"
model = "qwen2.5-0.5b"                 # Must match the --alias passed to llama-server
base_url = "http://127.0.0.1:8081/v1"  # llama-server OpenAI-compatible endpoint
api_key = "test"                       # Must match the --api-key passed to llama-server
timeout = 600

Generic OpenAI-compatible Chat Completions provider (Groq, Together AI, vLLM, etc.):

[research]
provider = "openai"
api_style = "chat_completions"
model = "your-model-name"
api_key = "your-api-key"
base_url = "https://api.your-provider.com/v1"
timeout = 600

Optional env variables for Open Deep Research tools:

• SERPAPI_API_KEY or SERPER_API_KEY: enable Google-style search
• HF_TOKEN: optional, logs into Hugging Face Hub for gated models

Install The Included Skill In Claude Code Or Codex

This repository also ships a repo-specific skill guide at [skills/deep-research-mcp/SKILL.md](skills/deep-research-mcp/SKILL.md).

Installing that file as a local skill gives Claude Code or Codex a focused playbook for this repository's CLI, Python API, providers, and MCP server. It does not install Python dependencies, start the MCP server, or replace the provider configuration in ~/.deep_research. Treat it as complementary to the MCP setup below, not a substitute for it.

Claude Code skill install

Claude Code's skills docs use these locations:

• personal skill: ~/.claude/skills//SKILL.md
• project skill: .claude/skills//SKILL.md

Personal install:

mkdir -p ~/.claude/skills/deep-research-mcp
cp /path/to/deep-research-mcp/skills/deep-research-mcp/SKILL.md \
  ~/.claude/skills/deep-research-mcp/SKILL.md

If you prefer to keep the installed skill linked to this checkout:

mkdir -p ~/.claude/skills/deep-research-mcp
ln -sf /path/to/deep-research-mcp/skills/deep-research-mcp/SKILL.md \
  ~/.claude/skills/deep-research-mcp/SKILL.md

Project-local install from the repository root:

mkdir -p .claude/skills/deep-research-mcp
cp skills/deep-research-mcp/SKILL.md .claude/skills/deep-research-mcp/SKILL.md

After that, restart Claude Code or open a new session if the skill does not appear immediately. The skill can be invoked directly as /deep-research-mcp, and Claude can also load it automatically when the task matches the skill description. For a reusable shared extension, package the same skill into a Claude Code plugin instead of copying it by hand.

Official docs:

• Claude Code skills:
• Claude Code plugins:

Codex skill install

Current Codex docs describe skills as skill folders containing SKILL.md, stored globally in $HOME/.agents/skills or repo-locally in .agents/skills.

Personal install:

mkdir -p ~/.agents/skills/deep-research-mcp
cp /path/to/deep-research-mcp/skills/deep-research-mcp/SKILL.md \
  ~/.agents/skills/deep-research-mcp/SKILL.md

Or keep the installed skill linked to this checkout:

mkdir -p ~/.agents/skills/deep-research-mcp
ln -sf /path/to/deep-research-mcp/skills/deep-research-mcp/SKILL.md \
  ~/.agents/skills/deep-research-mcp/SKILL.md

Project-local install from the repository root:

mkdir -p .agents/skills/deep-research-mcp
cp skills/deep-research-mcp/SKILL.md .agents/skills/deep-research-mcp/SKILL.md

If your Codex setup still follows older CLI conventions that use ~/.codex/skills or .codex/skills, mirror the same directory structure there instead.

Codex can invoke the skill implicitly when the task matches its description, or explicitly by mentioning $deep-research-mcp in the prompt. If the skill does not show up immediately, restart Codex.

Official docs:

• Codex skills:
• Codex customization and skill locations:

Claude Code Integration

1. Configure MCP Server

Choose one of the transports below.

Option A: stdio (recommended when Claude Code should spawn the server itself)

If your provider credentials are already stored in ~/.deep_research, the minimal setup is:

claude mcp add deep-research -- uv run --directory /path/to/deep-research-mcp deep-research-mcp

If you want Claude Code to pass OPENAI_API_KEY through to the spawned MCP process explicitly, use:

claude mcp add -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  deep-research -- \
  uv run --directory /path/to/deep-research-mcp deep-research-mcp

Option B: HTTP (recommended when you want to run the server separately)

Start the server in one terminal:

OPENAI_API_KEY="$OPENAI_API_KEY" \
uv run --directory /path/to/deep-research-mcp \
  deep-research-mcp --transport http --host 127.0.0.1 --port 8080

Then add the HTTP MCP server in Claude Code:

claude mcp add --transport http deep-research-http http://127.0.0.1:8080/mcp

Replace /path/to/deep-research-mcp/ with the actual path to your cloned repository. The verified Streamable HTTP endpoint is http://127.0.0.1:8080/mcp.

For multi-hour research, raise Claude Code's tool timeout before launching the CLI and rely on incremental status polls:

export MCP_TOOL_TIMEOUT=14400000  # 4 hours
claude --mcp-config ./.mcp.json

Kick off work with deep_research or research_with_context, note the returned job ID, and call research_status to stream progress without letting any single tool call stagnate.

Output size: Claude Code limits MCP tool output (about 25,000 tokens by default, configurable via MAX_MCP_OUTPUT_TOKENS). The research tools declare the anthropic/maxResultSizeChars annotation so recent Claude Code versions accept large reports without extra configuration; on older versions, raise the limit before launching the CLI:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Timeout recovery: if a research task exceeds the configured timeout, the server leaves the provider task running by default and returns its task ID; call research_status with that ID to retrieve the full report once it completes. Pass --cancel-on-timeout to deep-research-mcp (or set cancel_on_timeout = true in ~/.deep_research) to restore the old cancel behavior.

1. Use in Claude Code:

• The research tools will appear in Claude Code's tool palette
• Simply ask Claude to "research [your topic]" and it will use the Deep Research agent
• For clarified research, ask Claude to "research [topic] with clarification" to get follow-up questions

OpenAI Codex Integration

1. Configure MCP Server

Choose one of the transports below.

Option A: stdio (recommended when Codex should spawn the server itself)

Add the MCP server configuration to your ~/.codex/config.toml file:

[mcp_servers.deep-research]
command = "uv"
args = ["run", "--directory", "/path/to/deep-research-mcp", "deep-research-mcp"]
# If your provider credentials live in shell env vars rather than ~/.deep_research,
# pass them through to the MCP subprocess explicitly:
env_vars = ["OPENAI_API_KEY"]
startup_timeout_ms = 30000  # 30 seconds for server startup
request_timeout_ms = 7200000  # 2 hours for long-running research tasks
# Alternatively, set tool_timeout_sec when using newer Codex clients
# tool_timeout_sec = 14400.0     # 4 hours for deep research runs

Replace /path/to/deep-research-mcp/ with the actual path to your cloned repos

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pminervini
• Source: pminervini/deep-research-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.