SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI codingdeep-research-mcp

deep-research-mcp

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

Open website

About this tool

Purpose

deep-research-mcp is a Python-based deep research agent that integrates multiple research providers into MCP-capable assistants such as Claude Code through the Model Context Protocol (MCP). It enables the assistant to initiate deep research tasks and retrieve research reports.

Supported research providers

  • OpenAI: Responses API (including web search and code interpreter), Chat Completions API (for broad provider compatibility), or experimental ChatGPT subscription access via Codex OAuth.
  • Gemini Deep Research: via the Interactions API.
  • Tavily Research.
  • Allen AI's DR-Tulu research agent.
  • The open-source Open Deep Research stack (based on smolagents).
  • Additionally supports Perplexity (via Sonar Deep Research and OpenAI-compatible endpoints), Ollama (local), llama-server (local llama.cpp server), and generic OpenAI-compatible Chat Completions providers (such as Groq, Together AI, vLLM, etc.).

Main capabilities

  • Provides research tools to assistants such as Claude Code, OpenAI Codex, and Gemini CLI via MCP.
  • Provides the deep-research-cli command-line implementation.
  • Provides an interactive full-screen terminal UI (deep-research-tui.py) that can conduct research, check status, and save output to disk.
  • Provides the FastMCP server and tool entry point.
  • Supports asynchronous research tasks: after starting deep_research, a task ID is returned, and research_status can be called to poll progress and retrieve the full report; supports timeout recovery (by default the provider task is kept running and the task ID is returned; the old cancellation behavior can be restored via --cancel-on-timeout or cancel_on_timeout = true).
  • Some providers support native web search and Code Interpreter (such as the OpenAI Responses backend).

Usage

Configuration

Create a ~/.deep_research file in the user's home directory, using TOML format. The research configuration explicitly reads this file via ResearchConfig.load() and applies environment variable overrides; ResearchConfig.from_env() only reads environment variables. In common settings, [research] api_key and base_url map to the RESEARCH_API_KEY and RESEARCH_BASE_URL settings, applicable to every provider except openai-codex. For Tavily, TAVILY_API_KEY takes precedence over RESEARCH_API_KEY. The Codex subscription provider ignores API key and endpoint overrides.

Supports setting reasoning_effort (none, low, medium, high, xhigh, or max), with the environment variable RESEARCH_REASONING_EFFORT; CLI flags take precedence over environment variables and TOML values.

Running

No cloning required: after installing uv and Git, the packaged command can be run directly from GitHub, and uvx will build an isolated environment and reuse it from the local uv cache. The openai-codex device login can also be used without a checkout.

Source checkout: provides a recommended development setup (resolving the latest compatible versions) and a compatible setup (pip-based).

Integration

  • Claude Code: the MCP server can be configured via stdio (recommended that Claude Code start the server itself) or HTTP (recommended to run the server separately). stdio supports clone-free user installation and session checkout; HTTP requires starting the server in one terminal first, then adding the HTTP MCP server; the verified Streamable HTTP endpoint is http://127.0.0.1:8080/mcp。配置后研究工具会出现在 Claude Code tool panel; simply have Claude "research [your topic]" directly.
  • OpenAI Codex: Also supports stdio or HTTP. MCP server configuration can be added via ~/.codex/config.toml. Pay attention to timeout configuration: startup_timeout_ms (default 30000 milliseconds), request_timeout_ms (7200000 milliseconds/2 hours recommended for comprehensive research), tool_timeout_sec (newer Codex clients recommend setting a larger value, such as 14400.0 seconds/4 hours). You can first start a research run to obtain a task ID, then poll research_status.
  • Gemini CLI: Use its built-in command to add an MCP server, or manually add it to ~/.gemini/settings.json.

Skill Installation

The repository includes the skill guide skills/deep-research-mcp/SKILL.md. Installing it as a local skill provides Claude Code or Codex with an operations manual for this repository's CLI, Python API, providers, and MCP server. It does not install Python dependencies, does not start the MCP server, and does not replace provider configuration in ~/.deep_research.

Claude Code skill locations: personal skills ~/.claude/skills/<skill-name>/SKILL.md; project skills .claude/skills/<skill-name>/SKILL.md. In Claude Code, /deep-research-mcp can be executed, and Claude can also automatically load it when a task matches the skill description.

Codex skill locations: global $HOME/.agents/skills or repository-local .agents/skills. If Codex settings follow the old CLI convention (~/.codex/skills or .codex/skills), you can use the same directory structure. Codex can invoke it implicitly, or explicitly invoke it by mentioning $deep-research-mcp in the prompt.

Applicable Scenarios and Limitations

Applicable scenarios: Conduct deep research in MCP-supporting assistants such as Claude Code, OpenAI Codex, Gemini CLI, etc., covering multiple research provider options.

Limitations and notes:

  • The OpenAI Codex subscription provider uses an undocumented https://chatgpt.com/backend-api/codex consumer endpoint, is not an official OpenAI API integration, and may change or refuse third-party clients at any time; please review the current OpenAI terms of use before use. This provider's native web search is available, but Code Interpreter is not available; calls are synchronous SSE streams, and research_status, completed report recovery, background polling, and cancel_on_timeout are all unavailable; imported Codex credentials cannot be refreshed, and auth login must be run after the access token expires.
  • Tavily Research is an asynchronous task; use research_status and the task ID to recover the full report; Tavily does not expose task cancellation, so even if cancel_on_timeout = true, timed-out tasks may continue running.
  • The agent IDs for Gemini Deep Research are all preview identifiers and may change.
  • The DR-Tulu backend calls POST {base_url}/chat; if fronted through a different host, port, or reverse proxy, base_url must be updated accordingly.
  • Claude Code limits MCP tool output (about 25,000 tokens by default, configurable via MAX_MCP_OUTPUT_TOKENS); the research tool declares the anthropic/maxResultSizeChars annotation, and newer versions can directly accept large reports, while older versions need to raise the limit.
  • Multi-duration research requires increasing the Claude Code tool timeout and relying on incremental status polling.
  • Other specific billing, pricing, and similar information is not provided for now.

Related tools

Browse category