Deep Research MCP

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)
- 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:

Clone and configure dr-tulu separately.
In dr-tulu/agent/.env, set at least:
- SERPER_API_KEY
- JINA_API_KEY
- S2_API_KEY (optional but recommended)
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
'

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

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"

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.

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-name>/SKILL.md
project skill: .claude/skills/<skill-name>/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: https://docs.claude.com/en/docs/claude-code/skills
Claude Code plugins: https://docs.claude.com/en/docs/claude-code/plugins

Codex skill install

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

…

Deep Research

Installation

Configuration

How to use

README

Deep Research MCP

Prerequisites

Installation

Code Layout

Configuration

Configuration File

Install The Included Skill In Claude Code Or Codex

Claude Code skill install

Codex skill install

You might also like