pminervini/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, 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-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)
- 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:
For reproducible installation, replace main with a release tag or commit SHA.
The openai-codex device login is also available without a checkout:
Source Checkout
Recommended development setup (resolves the latest compatible versions):
Compatibility setup (pip-based):
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 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:
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.
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.
OpenAI Codex subscription provider example:
Authenticate before starting the CLI or MCP server:
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