Back to MCP Servers

Deep Research

Deep research MCP server for OpenAI Responses API or Open Deep Research (smolagents), with web search and code interpreter support.

researchapiaiagent
By pminervini
9412Updated 1 week agoPythonMIT

Installation

npx -y deep-research-mcp

Configuration

{
  "mcpServers": {
    "deep-research-mcp": {
      "command": "npx",
      "args": ["-y", "deep-research-mcp"]
    }
  }
}

How to use

  1. Run the installation command above (if needed)
  2. Open your Claude Code settings file (~/.claude/settings.json)
  3. Add the configuration to the mcpServers section
  4. Restart Claude Code to apply changes

README

View on GitHub

Deep Research MCP

CI License: MIT Python MCP Claude Code OpenAI Gemini

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, Chat Completions API for broad provider compatibility, or experimental ChatGPT subscription access through Codex OAuth), 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 model gpt-5.6-sol)
    • ChatGPT subscription with Codex access (experimental openai-codex provider)
    • 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

Run Without Cloning

With uv and Git installed, run the packaged commands directly from GitHub. uvx builds an isolated environment and reuses it from the local uv cache:

uvx --from "git+https://github.com/pminervini/deep-research-mcp.git@main" \
  deep-research-cli --help

uvx --from "git+https://github.com/pminervini/deep-research-mcp.git@main" \
  deep-research-mcp --help

For reproducible installation, replace main with a release tag or commit SHA. The openai-codex device login is also available without a checkout:

uvx --from "git+https://github.com/pminervini/deep-research-mcp.git@main" \
  deep-research-cli auth login

Source Checkout

Recommended development 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 callbacks and delegates provider work to backends
  • src/deep_research_mcp/backends/: provider-specific implementations for OpenAI, OpenAI Codex subscription, Gemini, DR-Tulu, and Open Deep Research
  • src/deep_research_mcp/cli.py: installed deep-research-cli implementation
  • src/deep_research_mcp/mcp_server.py: FastMCP server and tool entrypoints
  • cli/deep-research-cli.py: compatibility wrapper for source-checkout usage
  • cli/deep-research-tui.py: interactive full-screen terminal UI for research, status checks, and saving output to disk
  • tests/: pytest suite covering configuration, MCP integration, results, and UI 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", "openai-codex", "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 = "gpt-5.6-sol"                       # OpenAI: model identifier; Codex: "auto" or account model slug; 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; Codex uses a fixed 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

[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 except openai-codex. The Codex subscription provider ignores API keys and endpoint overrides so its bearer token cannot be redirected. If you switch another provider via an environment override (e.g. RESEARCH_PROVIDER=openai) while the file is configured for a different provider, also override RESEARCH_API_KEY and RESEARCH_BASE_URL.

OpenAI provider example:

[research]
provider = "openai"
model = "gpt-5.6-sol"                       # 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

OpenAI Codex subscription provider example:

[research]
provider = "openai-codex"
model = "auto"                              # First picker-visible account model
timeout = 1800

Authenticate before starting the CLI or MCP server:

# Recommended: independent device-code session
uv run deep-research-cli auth login

# Optional short-lived import; never copies the Codex refresh token
uv run deep-research-cli auth login --import-codex

uv run deep-research-cli auth status

Credentials are stored independently in ~/.deep_research_auth.json with owner-only permissions. auth logout removes only this file. Model names are loaded from the signed-in account's /models catalogue; an explicit model must be present in that catalogue.

This provider uses the undocumented https://chatgpt.com/backend-api/codex consumer endpoint. It is not an official OpenAI API integration and can change or reject third-party clients without notice. It identifies itself as deep_research_mcp and does not impersonate the Codex CLI. Review the current OpenAI Terms of Use before enabling it.

Limitations:

  • Native web search is enabled, but Code Interpreter is unavailable.
  • Calls are synchronous SSE streams; research_status, completed-report recovery, background polling, and cancel_on_timeout are unavailable.
  • Imported Codex credentials cannot refresh. Run auth login when the imported access token expires.

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)
  3. 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.

Inst

…

View source on GitHub

You might also like

Agentforge
MCP Servers
Katzilla
MCP Servers
Grok
MCP Servers