Deep Research MCP

What pminervini/deep-research-mcp does

The pminervini/deep-research-mcp MCP server connects an MCP-compatible assistant to several deep-research providers. Supported backends include OpenAI Responses API, OpenAI Chat Completions-compatible endpoints, the experimental OpenAI Codex subscription flow, Gemini Deep Research through the Interactions API, Allen AI’s DR-Tulu service, and the open-source Open Deep Research stack built around smolagents.

The OpenAI Responses API backend can use web search and Code Interpreter. Chat Completions mode is intended for broader provider compatibility, including services such as Perplexity, Groq, and Ollama when configured through a compatible endpoint. The project also includes a terminal interface for starting research, checking status, and saving results.

How it works

Provider selection and task behavior are controlled through a TOML configuration file or environment overrides. The orchestration layer delegates work to a provider-specific backend, while the MCP entrypoints expose the research workflow to the connected assistant. Long-running tasks can use a timeout and polling interval; when configured, a timed-out task may continue running so its result can later be recovered through status checks.

The Codex subscription backend differs from the API-based providers. It uses an authenticated device-login flow and synchronous server-sent event streams, so background polling, status recovery, and cancellation-on-timeout are not available for that provider.

Setup and configuration

The pminervini/deep-research-mcp MCP server requires Python 3.11 or newer and uv. A packaged command can be run directly from the GitHub repository with uvx, or the repository can be checked out and installed with uv sync. Optional dependencies are available for development, documentation, and Open Deep Research.

Create ~/.deep_research in TOML format. Under [research], set provider, model, and, where applicable, api_key and base_url. The provider defaults to OpenAI. API-key and endpoint settings map to RESEARCH_API_KEY and RESEARCH_BASE_URL; Codex ignores those overrides. OpenAI keys can also come from OPENAI_API_KEY, while Gemini keys default to GEMINI_API_KEY or GOOGLE_API_KEY.

Codex users must authenticate with deep-research-cli auth login. Credentials are stored separately in ~/.deep_research_auth.json; imported Codex access tokens cannot refresh after expiry.

Tools and capabilities

The pminervini/deep-research-mcp MCP server supports:

• Provider selection across OpenAI, OpenAI Codex, Gemini, DR-Tulu, and Open Deep Research.
• Web search through supported provider workflows.
• Code Interpreter through the OpenAI Responses API provider.
• Research task timeouts, polling intervals, and optional cancellation behavior.
• Status checks and recovery for supported background research tasks.
• CLI authentication, status inspection, interactive research, and output saving.

Limitations and notes

Provider features are not uniform. OpenAI Codex has no Code Interpreter and uses an undocumented consumer endpoint that may change. Gemini agent identifiers are preview versions and may change. DR-Tulu requires a service running locally or remotely, while Open Deep Research requires its optional dependency set.

The server does not remove the need for provider access. Running a hosted provider generally requires the corresponding API access or subscription, and endpoint compatibility depends on the selected backend. Review the provider’s terms and availability before relying on experimental or preview integrations.

Getting started with this pminervini/deep-research-mcp MCP server

Always refer to the official documentation for the most accurate and up-to-date information.