# pminervini/deep-research-mcp [Health: Active]

**Category:** 🔬 Research  
**Repository:** https://github.com/pminervini/deep-research-mcp  
**GitHub Stars:** 109  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/pminervini-deep-research-mcp

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "deep-research-mcp": {
    "command": "uvx",
    "args": ["--from"],
    "env": {
      "RESEARCH_PROVIDER": "",
      "RESEARCH_API_KEY": "",
      "RESEARCH_BASE_URL": "",
      "RESEARCH_MODEL": "",
      "RESEARCH_TIMEOUT": "",
      "RESEARCH_POLL_INTERVAL": "",
      "OPENAI_API_KEY": "",
      "GEMINI_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `RESEARCH_PROVIDER`, `RESEARCH_API_KEY`, `RESEARCH_BASE_URL`, `RESEARCH_MODEL`, `RESEARCH_TIMEOUT`, `RESEARCH_POLL_INTERVAL`, `OPENAI_API_KEY`, `GEMINI_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/pminervini-deep-research-mcp/readme_