deep-research-mcp

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, Chat Completions API for broad provider compatibility, or experimental ChatGPT subscription access through Codex OAuth), Gemini Deep Research via the Interactions API, Tavily Research, and self-hosted deployments of Allen AI's DR-Tulu and openJiuwen DeepSearch (Gnosis).

Prerequisites

• Python 3.11+
• uv installed
• One of:
  • OpenAI API access (Responses API model gpt-6-sol)
  • ChatGPT subscription with Codex access (experimental openai-codex provider)
  • Gemini API access with the Interactions API / Deep Research agent enabled
  • Tavily API access for Tavily Research
  • DR-Tulu service running locally or remotely (see DR-Tulu setup)
  • Gnosis/openJiuwen DeepSearch run service and a shared output directory (see Gnosis setup)
• 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

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, Tavily, DR-Tulu, and Gnosis
• 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", "tavily", "gnosis" -- defaults to "openai"
api_style = "responses"                     # Only applies to provider="openai"; use "chat_completions" for Perplexity, Groq, Ollama, etc.
model = "gpt-6-sol"                         # OpenAI: model identifier; Codex: "auto" or account model slug; Dr Tulu: logical provider id; Gemini: agent id; Tavily: "mini", "pro", or "auto"
reasoning_effort = "medium"                  # Optional for OpenAI API and Codex subscription; omit to keep provider/model defaults
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; Tavily: https://api.tavily.com

# 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"

# Optional named backends for the MCP server. Each table accepts the same keys
# as [research]; `provider` is required. MCP clients select one with the
# `backend` argument of `deep_research`; the [research] table is the "default"
# backend and is used when no name is given.
[backends.fast]
provider = "openai"
api_style = "chat_completions"
model = "llama-3.3-70b"
base_url = "https://api.groq.com/openai/v1"
api_key = "gsk-..."

[backends.tulu-lab]
provider = "dr-tulu"
base_url = "http://lab-box:8080/"

[backends.gemini]
provider = "gemini"                         # api_key falls back to GEMINI_API_KEY

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. For Tavily, TAVILY_API_KEY takes precedence over RESEARCH_API_KEY so a provider switch can use a Tavily-specific key. 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.

Named backends ([backends.<name>]) are isolated from the default: provider, model, api_style, api_key, base_url, and reasoning_effort never leak into them from [research] or from RESEARCH_* environment variables. When a table omits api_key or base_url, the provider's own environment variables (OPENAI_API_KEY, GEMINI_API_KEY, TAVILY_API_KEY, DR_TULU_BASE_URL, and so on) and provider defaults apply; when the table sets them, the table wins, including over TAVILY_API_KEY. Runtime settings (timeout, poll_interval, cancel_on_timeout, enable_reasoning_summaries, [logging] level) are inherited from [research] and the environment unless the table overrides them. Several backends may share a provider, so two Dr Tulu servers or two OpenAI-compatible endpoints are simply two tables. The name default is reserved and names must not contain :. The server validates every named backend at startup. The CLI and TUI use the default backend unless started with --backend NAME.

OpenAI provider example:

The default gpt-6-sol balances demanding research and cost; choose gpt-6-astra for maximum capability or gpt-6-luna for lower-cost work. The Responses backend enables web search and optional Code Interpreter. Chat Completions defaults to gpt-6-luna but does not enable hosted research tools. An OpenAI API key is separate from the experimental ChatGPT Codex subscription login below. See OpenAI model guidance.

Set reasoning_effort to none, low, medium, high, xhigh, or max for OpenAI Responses, Chat Completions, or the Codex subscription provider. Supported efforts vary by model; OpenAI returns an error for unsupported combinations. If omitted, the Responses backend retains its existing GPT-5/6 research defaults (including xhigh for GPT-6), while Codex and Chat Completions leave effort to the provider. This is separate from reasoning summaries (enable_reasoning_summaries). Environment variable: RESEARCH_REASONING_EFFORT. CLI flags override environment and TOML values.

[research]
provider = "openai"
model = "gpt-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. The catalogue request uses a fallback Codex client version of 0.156.1; if codex is installed on PATH and reports a newer stable version, that version is used instead. An older, missing, or unparseable CLI leaves the fallback in place. model = "auto" selects the first picker-visible model returned by the catalogue, not necessarily the newest.

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

Gemini Deep Research agent IDs supported by this project:

Google's current Gemini Deep Research documentation lists the April 2026 standard and Max agents as the supported versions. The