Skip to content
Back to search

deep-research-mcp

MCP server for OpenAI Deep Research, Gemini Deep Research, Tavily Research, DR-Tulu, and Open Deep Research

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/pminervini/deep-research-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/pminervini/deep-research-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pminervini--deep-research-mcp/badge.svg)](/listings/pminervini--deep-research-mcp)

HTML

<a href="/listings/pminervini--deep-research-mcp"><img src="/api/listings/pminervini--deep-research-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

# Optional Open Deep Research provider dependencies
uv sync --upgrade --extra open-deep-research

Compatibility setup (pip-based):

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,412 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Deep Research MCP
  2. [![CI](https://img.shields.io/github/actions/workflow/status/pminervini/deep-research-mcp/ci.yml?branch=main&label=CI)](https://github.com/pminervini/deep-research-mcp/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  4. [![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
  5. [![MCP](https://img.shields.io/badge/MCP-compatible-4a5568)](https://modelcontextprotocol.io/)
  6. [![Claude Code](https://img.shields.io/badge/Claude_Code-ready-cc785c)](https://github.com/pminervini/deep-research-mcp#claude-code-integration)
  7. [![OpenAI](https://img.shields.io/badge/OpenAI-compatible-10a37f)](https://platform.openai.com/)
  8. [![Gemini](https://img.shields.io/badge/Gemini-supported-4285F4)](https://ai.google.dev/)
  9. [![openJiuwen](https://img.shields.io/badge/openJiuwen-supported-2563eb.svg)](#gnosis-provider-example)
  10. 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).
  11. ## Prerequisites
  12. - Python 3.11+
  13. - [uv](https://docs.astral.sh/uv/) installed
  14. - One of:
  15. - OpenAI API access (Responses API model `gpt-6.1-sol`)
  16. - ChatGPT subscription with Codex access (experimental `openai-codex` provider)
  17. - Gemini API access with the Interactions API / Deep Research agent enabled
  18. - Tavily API access for Tavily Research
  19. - DR-Tulu service running locally or remotely (see [DR-Tulu setup](#dr-tulu-provider-example))
  20. - Gnosis/openJiuwen DeepSearch run service and a shared output directory (see [Gnosis setup](#gnosis-provider-example))
  21. - Claude Code, or any other assistant supporting MCP integration
  22. ## Installation
  23. ### Run Without Cloning
  24. With `uv` and Git installed, run the packaged commands directly from GitHub.
  25. `uvx` builds an isolated environment and reuses it from the local uv cache:
  26. ```bash
  27. uvx --from "git+https://github.com/pminervini/deep-research-mcp.git@main" \
  28. deep-research-cli --help
  29. uvx --from "git+https://github.com/pminervini/deep-research-mcp.git@main" \
  30. deep-research-mcp --help
  31. ```
  32. For reproducible installation, replace `main` with a release tag or commit SHA.
  33. The `openai-codex` device login is also available without a checkout:
  34. ```bash
  35. uvx --from "git+https://github.com/pminervini/deep-research-mcp.git@main" \
  36. deep-research-cli auth login
  37. ```
  38. ### Source Checkout
  39. Recommended development setup (resolves the latest compatible versions):
  40. ```bash
  41. # Install runtime dependencies + project in editable mode
  42. uv sync --upgrade
  43. # Development tooling (pytest, black, pylint, mypy, pre-commit)
  44. uv sync --upgrade --extra dev
  45. # Enable the pre-commit hook so black runs automatically before each commit
  46. uv run pre-commit install
  47. # Optional docs tooling
  48. uv sync --upgrade --extra docs
  49. ```
  50. Compatibility setup (pip-based):
  51. ```bash
  52. python -m venv .venv
  53. source .venv/bin/activate
  54. pip install -r requirements.txt
  55. pip install -e .
  56. ```
  57. ## Code Layout
  58. - `src/deep_research_mcp/agent.py`: orchestration layer; owns callbacks and delegates provider work to backends
  59. - `src/deep_research_mcp/backends/`: provider-specific implementations for OpenAI, OpenAI Codex subscription, Gemini, Tavily, DR-Tulu, and Gnosis
  60. - `src/deep_research_mcp/cli.py`: installed `deep-research-cli` implementation
  61. - `src/deep_research_mcp/mcp_server.py`: FastMCP server and tool entrypoints
  62. - `cli/deep-research-cli.py`: compatibility wrapper for source-checkout usage
  63. - `cli/deep-research-tui.py`: interactive full-screen terminal UI for research, status checks, and saving output to disk
  64. - `tests/`: `pytest` suite covering configuration, MCP integration, results, and UI flows
  65. ## Configuration
  66. ### Configuration File
  67. Create a `~/.deep_research` file in your home directory using TOML format.
  68. Library note: `ResearchConfig.load()` explicitly reads this file and applies environment variable overrides. `ResearchConfig.from_env()` reads environment variables only.
  69. Common settings:
  70. ```toml
  71. [research] # Core Deep Research functionality
  72. provider = "openai" # Available options: "openai", "openai-codex", "dr-tulu", "gemini", "tavily", "gnosis" -- defaults to "openai"
  73. api_style = "responses" # Only applies to provider="openai"; use "chat_completions" for Perplexity, Groq, Ollama, etc.
  74. model = "gpt-6.1-sol" # OpenAI: model identifier; Codex: "auto" or account model slug; Dr Tulu: logical provider id; Gemini: agent id; Tavily: "mini", "pro", or "auto"
  75. reasoning_effort = "medium" # Optional for OpenAI API and Codex subscription; omit to keep provider/model defaults
  76. api_key = "your-api-key" # API key, optional
  77. 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
  78. # Task behavior
  79. timeout = 1800
  80. poll_interval = 30
  81. 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
  82. [logging]
  83. level = "INFO"
  84. # Optional named backends for the MCP server. Each table accepts the same keys
  85. # as [research]; `provider` is required. MCP clients select one with the
  86. # `backend` argument of `deep_research`; the [research] table is the "default"
  87. # backend and is used when no name is given.
  88. [backends.fast]
  89. provider = "openai"
  90. api_style = "chat_completions"
  91. model = "llama-3.3-70b"
  92. base_url = "https://api.groq.com/openai/v1"
  93. api_key = "gsk-..."
  94. [backends.tulu-lab]
  95. provider = "dr-tulu"
  96. base_url = "http://lab-box:8080/"
  97. [backends.gemini]
  98. provider = "gemini" # api_key falls back to GEMINI_API_KEY
  99. ```
  100. 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`.
  101. 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`.
  102. OpenAI provider example:
  103. The default `gpt-6.1-sol` balances demanding research and cost; choose
  104. `gpt-6-astra` for maximum capability or `gpt-6-luna` for lower-cost work.
  105. The Responses backend enables web search and optional Code Interpreter.
  106. Chat Completions defaults to `gpt-6-luna` but does not enable hosted research
  107. tools. An OpenAI API key is separate from the experimental ChatGPT Codex
  108. subscription login below. See [OpenAI model guidance](https://developers.openai.com/api/docs/guides/latest-model).
  109. Set `reasoning_effort` to `none`, `low`, `medium`, `high`, `xhigh`, or `max`
  110. for OpenAI Responses, Chat Completions, or the Codex subscription provider.
  111. Supported efforts vary by model; OpenAI returns an error for unsupported
  112. combinations. If omitted, the Responses backend retains its existing GPT-5/6
  113. research defaults (including `xhigh` for GPT-6), while Codex and Chat
  114. Completions leave effort to the provider. This is separate from reasoning
  115. summaries (`enable_reasoning_summaries`). Environment variable:
  116. `RESEARCH_REASONING_EFFORT`. CLI flags override environment and TOML values.
  117. ```toml
  118. [research]
  119. provider = "openai"
  120. model = "gpt-6.1-sol" # OpenAI model
  121. api_key = "YOUR_OPENAI_API_KEY" # Defaults to OPENAI_API_KEY
  122. base_url = "https://api.openai.com/v1" # OpenAI-compatible endpoint
  123. timeout = 1800
  124. poll_interval = 30
  125. ```
  126. OpenAI Codex subscription provider example:
  127. ```toml
  128. [research]
  129. provider = "openai-codex"
  130. model = "auto" # First picker-visible account model
  131. timeout = 1800
  132. ```
  133. Authenticate before starting the CLI or MCP server:
  134. ```bash
  135. # Recommended: independent device-code session
  136. uv run deep-research-cli auth login
  137. # Optional short-lived import; never copies the Codex refresh token
  138. uv run deep-research-cli auth login --import-codex
  139. uv run deep-research-cli auth status
  140. ```
  141. Credentials are stored independently in `~/.deep_research_auth.json` with
  142. owner-only permissions. `auth logout` removes only this file. Model names are
  143. loaded from the signed-in account's `/models` catalogue; an explicit model must
  144. be present in that catalogue. The catalogue request uses a fallback Codex client
  145. version of `0.156.1`; if `codex` is installed on `PATH` and reports a newer
  146. stable version, that version is used instead. An older, missing, or unparseable
  147. CLI leaves the fallback in place. `model = "auto"` selects the first
  148. picker-visible model returned by the catalogue, not necessarily the newest.
  149. This provider uses the undocumented
  150. `https://chatgpt.com/backend-api/codex` consumer endpoint. It is not an official
  151. OpenAI API integration and can change or reject third-party clients without
  152. notice. It identifies itself as `deep_research_mcp` and does not impersonate the
  153. Codex CLI. Review the current [OpenAI Terms of
  154. Use](https://openai.com/policies/terms-of-use/) before enabling it.
  155. Limitations:
  156. - Native web search is enabled, but Code Interpreter is unavailable.
  157. - Calls are synchronous SSE streams; `research_status`, completed-report
  158. recovery, background polling, and `cancel_on_timeout` are unavailable.
  159. - Imported Codex credentials cannot refresh. Run `auth login` when the imported
  160. access token expires.
  161. Gemini Deep Research provider example:
  162. ```toml
  163. [research]
  164. provider = "gemini"
  165. model = "deep-research-preview-04-2026" # Gemini Deep Research agent id
  166. api_key = "YOUR_GEMINI_API_KEY" # Defaults to GEMINI_API_KEY or GOOGLE_API_KEY
  167. base_url = "https://generativelanguage.googleapis.com"
  168. timeout = 1800
  169. poll_interval = 30
  170. ```
  171. Gemini Deep Research agent IDs supported by this project:
  172. | Agent ID | Intended use |
  173. | --- | --- |
  174. | `deep-research-preview-04-2026` | Faster, more efficient research; this is the project default |
  175. | `deep-research-max-preview-04-2026` | Maximum comprehensiveness for context gathering and synthesis |
  176. | `deep-research-pro-preview-12-2025` | Older Gemini 3.1 Pro-based preview for accuracy-focused, long-running research |
  177. Google's current [Gemini Deep Research documentation](https://ai.google.dev/gemini-api/docs/deep-research)
  178. lists the April 2026 standard and Max agents as the supported versions. The
  179. December 2025 Pro agent has a separate [model page](https://ai.google.dev/gemini-api/docs/models/deep-research-pro-preview-12-2025),
  180. and its ID (`deep-research-pro-preview-12-2025`) still appears in the
  181. [Interactions API reference](https://ai.google.dev/api/interactions-api). It is
  182. not listed in the current [model catalogue](https://ai.google.dev/gemini-api/docs/models),
  183. but a live research task completed through this project with that ID on
  184. September 27, 2026. Set any agent ID above as `research.model`; all are preview
  185. identifiers and may change.
  186. Tavily Research provider example:
  187. ```toml
  188. [research]
  189. provider = "tavily"
  190. model = "mini" # "mini", "pro", or "auto"; defaults to "mini"
  191. base_url = "https://api.tavily.com"
  192. timeout = 1800
  193. poll_interval = 30
  194. ```
  195. Set `TAVILY_API_KEY` in your environment or set `api_key` in
  196. `~/.deep_research`. Tavily Research starts an asynchronous task; use
  197. `research_status` with its task ID to recover a completed report. Tavily does
  198. not expose task cancellation, so a timed-out task may keep running even when
  199. `cancel_on_timeout = true`. See [Tavily Research API](https://docs.tavily.com/documentation/api-reference/endpoint/research)
  200. and [credit costs](https://docs.tavily.com/documentation/api-credits).
  201. ```bash
  202. uv run deep-research-cli research "What changed in Python 3.0?"
  203. ```
  204. ### Gnosis provider example
  205. Gnosis uses the state-space `search` workflow in
  206. [openJiuwen DeepSearch](https://github.com/openJiuwen-ai/deepsearch), not its
  207. separate report-generation API. Deploy that service independently and publish
  208. its run/telemetry port (8089). The adapter adds no openJiuwen SDK dependency.
  209. ```toml
  210. [backends.gnosis]
  211. provider = "gnosis"
  212. base_url = "http://127.0.0.1:8089"
  213. gnosis_config_path = "/absolute/path/to/gnosis-options.json"
  214. gnosis_output_dir = "/absolute/path/to/shared/output"
  215. timeout = 240
  216. poll_interval = 2
  217. cancel_on_timeout = true
  218. ```
  219. `gnosis_config_path` points to a private JSON file containing the native
  220. `POST /runs` request options: `llm`, `tool_map`, search/fetch provider settings,
  221. and optional `search_workflow_per_question_params`. Use the deployed service's
  222. `/docs` for its schema. Do not put `query`, `run_id`, or `conversation_id` in this
  223. file; the adapter owns them. It sets `search_mode="search"` and disables question
  224. routing so a run cannot silently switch to the differently bounded ReAct mode.
  225. For example, a stock service using Tavily and Jina accepts:
  226. ```json
  227. {
  228. "llm": {
  229. "model_name": "YOUR_CHAT_MODEL",
  230. "base_url": "https://api.openai.com/v1",
  231. "api_key": "YOUR_LLM_API_KEY"
  232. },
  233. "tool_map": "search_fetch",
  234. "web_search_engine_config": {
  235. "search_engine_name": "tavily",
  236. "search_api_key": "YOUR_TAVILY_API_KEY"
  237. },
  238. "web_fetch_provider_config": {
  239. "provider_name": "jina",
  240. "api_key": "YOUR_JINA_API_KEY"
  241. },
  242. "search_workflow_per_question_params": {
  243. "max_workers": 2,
  244. "time_limit": 180,
  245. "actions_explored_limit": 10,
  246. "fail_limit": 2
  247. }
  248. }
  249. ```
  250. Protect that file (`chmod 600`) and keep it outside the repository. The model
  251. and its reasoning options belong inside `llm`; the top-level `model="gnosis"`
  252. is only a logical provider label. Codex OAuth cannot be passed directly as a
  253. Chat Completions API key; subscription use requires a separately configured
  254. compatible bridge. Search/fetch tools remain a separate service configuration.
  255. The run API exposes completion metadata, not the full answer. The adapter reads
  256. `logs/result_<internal-conversation-id>/final_result.json` under
  257. `gnosis_output_dir`; mount the same output directory into the MCP process if
  258. it runs in another container. HTTP access alone is insufficient for recovery.
  259. Fresh clients can recover completed answers without loading the credential file.
  260. Unknown or nonterminal telemetry is reported as `unknown`, because the service
  261. does not expose live run status after a restart. Server restarts do not resume
  262. in-flight searches. `cancel_on_timeout` requests cancellation; otherwise the
  263. task ID is retained for later recovery. Graph action/time limits are not hard
  264. request/token budgets.
  265. Only confirmed, nonempty predictions count as completed answers. Guesses and
  266. limit exits without a confirmed answer are failures. Citations are extracted
  267. only from links in the selected answer, not inferred from visited pages. Code
  268. Interpreter is unsupported. This mode may return a short answer rather than
  269. a long research report.
  270. ```bash
  271. uv run deep-research-cli --backend gnosis research "When was Python 3.0 released?"
  272. uv run deep-research-cli --backend gnosis status RUN_ID
  273. ```
  274. Equivalent default-provider flags are `--provider gnosis`,
  275. `--gnosis-config-path PATH`, and `--gnosis-output-dir PATH`. Environment aliases:
  276. `GNOSIS_BASE_URL`, `GNOSIS_CONFIG_PATH`, `GNOSIS_OUTPUT_DIR`; optional
  277. `GNOSIS_API_KEY` authenticates the run service, not its LLM. Generic aliases
  278. `RESEARCH_GNOSIS_CONFIG_PATH` and `RESEARCH_GNOSIS_OUTPUT_DIR` apply only to the
  279. default backend; named tables remain isolated.
  280. Dr Tulu provider example:
  281. ```toml
  282. [research]
  283. provider = "dr-tulu"
  284. model = "dr-tulu" # Logical provider model id; currently informational
  285. base_url = "http://localhost:8080/" # Dr Tulu service base URL; the backend calls /chat
  286. api_key = "" # Optional; defaults to RESEARCH_API_KEY / DR_TULU_API_KEY if set
  287. timeout = 1800
  288. poll_interval = 30
  289. ```
  290. Running Dr Tulu locally:
  291. 1. Clone and configure [`dr-tulu`](https://github.com/allenai/dr-tulu) separately.
  292. 2. In `dr-tulu/agent/.env`, set at least:
  293. - `SERPER_API_KEY`
  294. - `JINA_API_KEY`
  295. - `S2_API_KEY` (optional but recommended)
  296. 3. Start the DR-Tulu model server:
  297. ```bash
  298. cd /path/to/dr-tulu/agent
  299. conda run -n vllm bash -lc '
  300. CUDA_VISIBLE_DEVICES=0 \
  301. vllm serve rl-research/DR-Tulu-8B \
  302. --port 30001 \
  303. --dtype auto \
  304. --max-model-len 16384 \
  305. --gpu-memory-utilization 0.60 \
  306. --enforce-eager
  307. '
  308. ```
  309. 4. Start the Dr Tulu MCP backend:
  310. ```bash
  311. cd /path/to/dr-tulu/agent
  312. conda run -n vllm python -m dr_agent.mcp_backend.main --port 8000
  313. ```
  314. 5. Start the Dr Tulu app service:
  315. ```bash
  316. cd /path/to/dr-tulu/agent
  317. conda run -n vllm python workflows/auto_search_sft.py serve \
  318. --port 8080 \
  319. --config workflows/auto_search_sft.yaml \
  320. --config-overrides "search_agent_max_tokens=12000,browse_agent_max_tokens=12000"
  321. ```
  322. 6. Point `deep-research-mcp` at that service:
  323. ```toml
  324. [research]
  325. provider = "dr-tulu"
  326. base_url = "http://localhost:8080/"
  327. timeout = 1800
  328. ```
  329. The `dr-tulu` backend calls `POST {base_url}/chat`, so if you front Dr Tulu behind a different host, port, or reverse proxy, update `base_url` accordingly.
  330. Perplexity (via [Sonar Deep Research](https://docs.perplexity.ai/getting-started/models/models/sonar-deep-research) and Perplexity's [OpenAI-compatible endpoint](https://docs.perplexity.ai/guides/chat-completions-guide)) provider example:
  331. ```toml
  332. [research]
  333. provider = "openai"
  334. api_style = "chat_completions" # Required for Perplexity (no Responses API)
  335. model = "sonar-deep-research" # Perplexity's Sonar Deep Research
  336. api_key = "ppl-..." # Defaults to OPENAI_API_KEY
  337. base_url = "https://api.perplexity.ai" # Perplexity's OpenAI-compatible endpoint
  338. timeout = 1800
  339. ```
  340. Ollama (local) provider example:
  341. ```toml
  342. [research]
  343. provider = "openai"
  344. api_style = "chat_completions"
  345. model = "llama3.1" # Any model available in your Ollama instance
  346. base_url = "http://localhost:11434/v1" # Ollama's OpenAI-compatible endpoint
  347. api_key = "" # Not required for local Ollama
  348. timeout = 600
  349. ```
  350. llama-server (local llama.cpp server) provider example:
  351. ```toml
  352. [research]
  353. provider = "openai"
  354. api_style = "chat_completions"
  355. model = "qwen2.5-0.5b" # Must match the --alias passed to llama-server
  356. base_url = "http://127.0.0.1:8081/v1" # llama-server OpenAI-compatible endpoint
  357. api_key = "test" # Must match the --api-key passed to llama-server
  358. timeout = 600
  359. ```
  360. Generic OpenAI-compatible Chat Completions provider (Groq, Together AI, vLLM, etc.):
  361. ```toml
  362. [research]
  363. provider = "openai"
  364. api_style = "chat_completions"
  365. model = "your-model-name"
  366. api_key = "your-api-key"
  367. base_url = "https://api.your-provider.com/v1"
  368. timeout = 600
  369. ```
  370. ### Install The Included Skill In Claude Code Or Codex
  371. This repository also ships a repo-specific skill guide at
  372. [`skills/deep-research-mcp/SKILL.md`](skills/deep-research-mcp/SKILL.md).
  373. Installing that file as a local skill gives Claude Code or Codex a focused
  374. playbook for this repository's CLI, Python API, providers, and MCP server.
  375. It does **not** install Python dependencies, start the MCP server, or replace
  376. the provider configuration in `~/.deep_research`. Treat it as complementary to
  377. the MCP setup below, not a substitute for it.
  378. #### Claude Code skill install
  379. Claude Code's skills docs use these locations:
  380. - personal skill: `~/.claude/skills/<skill-name>/SKILL.md`
  381. - project skill: `.claude/skills/<skill-name>/SKILL.md`
  382. Personal install:
  383. ```bash
  384. mkdir -p ~/.claude/skills/deep-research-mcp
  385. cp /path/to/deep-research-mcp/skills/deep-research-mcp/SKILL.md \
  386. ~/.claude/skills/deep-research-mcp/SKILL.md
  387. ```
  388. If you prefer to keep the installed skill linked to this checkout:
  389. ```bash
  390. mkdir -p ~/.claude/skills/deep-research-mcp
  391. ln -sf /path/to/deep-research-mcp/skills/deep-research-mcp/SKILL.md \
  392. ~/.claude/skills/deep-research-mcp/SKILL.md
  393. ```
  394. Project-local install from the repository root:
  395. ```bash
  396. mkdir -p .claude/skills/deep-research-mcp
  397. cp skills/deep-research-mcp/SKILL.md .claude/skills/deep-research-mcp/SKILL.md
  398. ```
  399. After that, restart Claude Code or open a new session if the skill does not
  400. appear immediately. The skill can be invoked directly as
  401. `/deep-research-mcp`, and Claude can also load it automatically when the task
  402. matches the skill description. For a reusable shared extension, package the
  403. same skill into a Claude Code plugin instead of copying it by hand.
  404. Official docs:
  405. - Claude Code skills: <https://docs.claude.com/en/docs/claude-code/skills>
  406. - Claude Code plugins: <https://docs.claude.com/en/docs/claude-code/plugins>
  407. #### Codex skill install
  408. Current Codex docs describe skills as skill folders containing `SKILL.md`,
  409. stored globally in `$HOME/.agents/skills` or repo-locally in `.agents/skills`.
  410. Personal install:
  411. ```bash
  412. mkdir -p ~/.agents/skills/deep-research-mcp
  413. cp /path/to/deep-research-mcp/skills/deep-research-mcp/SKILL.md \
  414. ~/.agents/skills/deep-research-mcp/SKILL.md
  415. ```
  416. Or keep the installed skill linked to this checkout:
  417. ```bash
  418. mkdir -p ~/.agents/skills/deep-research-mcp
  419. ln -sf /path/to/deep-research-mcp/skills/deep-research-mcp/SKILL.md \
  420. ~/.agents/skills/deep-research-mcp/SKILL.md
  421. ```
  422. Project-local install from the repository root:
  423. ```bash
  424. mkdir -p .agents/skills/deep-research-mcp
  425. cp skills/deep-research-mcp/SKILL.md .agents/skills/deep-research-mcp/SKILL.md
  426. ```
  427. If your Codex setup still follows older CLI conventions that use
  428. `~/.codex/skills` or `.codex/skills`, mirror the same directory structure
  429. there instead.
  430. Codex can invoke the skill implicitly when the task matches its description, or
  431. explicitly by mentioning `$deep-research-mcp` in the prompt. If the skill does
  432. not show up immediately, restart Codex.
  433. Official docs:
  434. - Codex skills: <https://developers.openai.com/codex/skills>
  435. - Codex customization and skill locations: <https://developers.openai.com/codex/concepts/customization#skills>
  436. ### Claude Code Integration
  437. 1. **Configure MCP Server**
  438. Choose one of the transports below.
  439. **Option A: stdio (recommended when Claude Code should spawn the server itself)**
  440. Clone-free user installation:
  441. ```bash
  442. claude mcp add --scope user --transport stdio deep-research -- \
  443. uvx --from "git+https://github.com/pminervini/deep-research-mcp.git@main" \
  444. deep-research-mcp
  445. ```
  446. For a source checkout with provider credentials already stored in
  447. `~/.deep_research`, use:
  448. ```bash
  449. claude mcp add deep-research -- uv run --directory /path/to/deep-research-mcp deep-research-mcp
  450. ```
  451. If you want Claude Code to pass `OPENAI_API_KEY` through to the spawned MCP
  452. process explicitly, use:
  453. ```bash
  454. claude mcp add -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  455. deep-research -- \
  456. uv run --directory /path/to/deep-research-mcp deep-research-mcp
  457. ```
  458. **Option B: HTTP (recommended when you want to run the server separately)**
  459. Start the server in one terminal:
  460. ```bash
  461. OPENAI_API_KEY="$OPENAI_API_KEY" \
  462. uv run --directory /path/to/deep-research-mcp \
  463. deep-research-mcp --transport http --host 127.0.0.1 --port 8080
  464. ```
  465. Then add the HTTP MCP server in Claude Code:
  466. ```bash
  467. claude mcp add --transport http deep-research-http http://127.0.0.1:8080/mcp
  468. ```
  469. Replace `/path/to/deep-research-mcp/` with the actual path to your cloned repository.
  470. The verified Streamable HTTP endpoint is `http://127.0.0.1:8080/mcp`.
  471. For multi-hour research, raise Claude Code's tool timeout before launching the CLI and rely on incremental status polls:
  472. ```bash
  473. export MCP_TOOL_TIMEOUT=14400000 # 4 hours
  474. claude --mcp-config ./.mcp.json
  475. ```
  476. Kick off work with `deep_research`, note the returned job ID, and call `research_status` to stream progress without letting any single tool call stagnate. Task IDs are returned as `<backend>:<provider task id>` (for example `default:resp_abc123`) and must be passed back to `research_status` verbatim; an un-prefixed ID is looked up on the default backend. If `~/.deep_research` declares `[backends.<name>]` tables, call `list_backends` to see them and pass `backend="<name>"` to `deep_research` to use one.
  477. Output size: Claude Code limits MCP tool output (about 25,000 tokens by default, configurable via `MAX_MCP_OUTPUT_TOKENS`). The research tools declare the `anthropic/maxResultSizeChars` annotation so recent Claude Code versions accept large reports without extra configuration; on older versions, raise the limit before launching the CLI:
  478. ```bash
  479. export MAX_MCP_OUTPUT_TOKENS=50000
  480. claude
  481. ```
  482. Timeout recovery: if a research task exceeds the configured `timeout`, the server leaves the provider task running by default and returns its task ID; call `research_status` with that ID to retrieve the full report once it completes. Pass `--cancel-on-timeout` to `deep-research-mcp` (or set `cancel_on_timeout = true` in `~/.deep_research`) to restore the old cancel behavior.
  483. 2. **Use in Claude Code**:
  484. - The research tools will appear in Claude Code's tool palette
  485. - Simply ask Claude to "research [your topic]" and it will use the Deep Research agent
  486. ### OpenAI Codex Integration
  487. 1. **Configure MCP Server**
  488. Choose one of the transports below.
  489. **Option A: stdio (recommended when Codex should spawn the server itself)**
  490. Clone-free installation:
  491. ```bash
  492. codex mcp add deep-research -- \
  493. uvx --from "git+https://github.com/pminervini/deep-research-mcp.git@main" \
  494. deep-research-mcp
  495. ```
  496. For a source checkout, add the MCP server configuration to
  497. `~/.codex/config.toml`:
  498. ```toml
  499. [mcp_servers.deep-research]
  500. command = "uv"
  501. args = ["run", "--directory", "/path/to/deep-research-mcp", "deep-research-mcp"]
  502. # If your provider credentials live in shell env vars rather than ~/.deep_research,
  503. # pass them through to the MCP subprocess explicitly:
  504. env_vars = ["OPENAI_API_KEY"]
  505. startup_timeout_ms = 30000 # 30 seconds for server startup
  506. request_timeout_ms = 7200000 # 2 hours for long-running research tasks
  507. # Alternatively, set tool_timeout_sec when using newer Codex clients
  508. # tool_timeout_sec = 14400.0 # 4 hours for deep research runs
  509. ```
  510. Replace `/path/to/deep-research-mcp/` with the actual path to your cloned repository.
  511. If your credentials are already configured in `~/.deep_research`, `env_vars` is
  512. optional. It is required when you expect the spawned MCP server to inherit
  513. `OPENAI_API_KEY` from the parent shell.
  514. **Option B: HTTP (recommended when you want to run the server separately)**
  515. Start the server in one terminal:
  516. ```bash
  517. OPENAI_API_KEY="$OPENAI_API_KEY" \
  518. uv run --directory /path/to/deep-research-mcp \
  519. deep-research-mcp --transport http --host 127.0.0.1 --port 8080
  520. ```
  521. Then add this to `~/.codex/config.toml`:
  522. ```toml
  523. [mcp_servers.deep-research-http]
  524. url = "http://127.0.0.1:8080/mcp"
  525. tool_timeout_sec = 14400.0
  526. ```
  527. The verified Streamable HTTP endpoint is `http://127.0.0.1:8080/mcp`.
  528. **Important timeout configuration:**
  529. - `startup_timeout_ms`: Time allowed for the MCP server to start (default: 30000ms / 30 seconds)
  530. - `request_timeout_ms`: Maximum time for research queries to complete (recommended: 7200000ms / 2 hours for comprehensive research)
  531. - `tool_timeout_sec`: Preferred for newer Codex clients; set this to a large value (e.g., `14400.0` for 4 hours) when you expect long-running research.
  532. - Kick off research once to capture the job ID, then poll `research_status` so each tool call remains short and avoids hitting client timeouts.
  533. Without proper timeout configuration, long-running research queries may fail with "request timed out" errors.
  534. 2. **Use in OpenAI Codex**:
  535. - The research tools will be available automatically when you start Codex
  536. - Ask Codex to "research [your topic]" and it will use the Deep Research MCP server
  537. ### Gemini CLI Integration
  538. 1. **Configure MCP Server**
  539. Add the MCP server using Gemini CLI's built-in command:
  540. ```bash
  541. gemini mcp add deep-research -- uv run --directory /path/to/deep-research-mcp deep-research-mcp
  542. ```
  543. Or manually add to your `~/.gemini/settings.json` file:
  544. ```json
  545. {
  546. "mcpServers": {
  547. "deep-research": {
  548. "command": "uv",
  549. "args": ["run", "--directory", "/path/to/deep-research-mcp", "deep-research-mcp"],
  550. "env": {
  551. "RESEARCH_PROVIDER": "gemini",
  552. "GEMINI_API_KEY": "$GEMINI_API_KEY"
  553. }
  554. }
  555. }
  556. }
  557. ```
  558. Replace `/path/to/deep-research-mcp/` with the actual path to your cloned repository.
  559. 2. **Use in Gemini CLI**:
  560. - Start Gemini CLI with `gemini`
  561. - The research tools will be available automatically
  562. - Ask Gemini to "research [your topic]" and it will use the Deep Research MCP server
  563. - Use `/mcp` command to view server status and available tools
  564. HTTP transport: If your Gemini environment supports MCP-over-HTTP, you may run
  565. the server with `--transport http` and configure Gemini with the server URL.
  566. ## Usage
  567. ### As a Standalone Python Module
  568. ```python
  569. import asyncio
  570. from deep_research_mcp.agent import DeepResearchAgent
  571. from deep_research_mcp.config import ResearchConfig
  572. async def main():
  573. # Initialize configuration
  574. config = ResearchConfig.load()
  575. # Create agent
  576. agent = DeepResearchAgent(config)
  577. # Perform research
  578. result = await agent.research(
  579. query="What are the latest advances in quantum computing?",
  580. system_prompt="Focus on practical applications and recent breakthroughs"
  581. )
  582. # Print results
  583. print(f"Report: {result.final_report}")
  584. print(f"Citations: {result.citations}")
  585. print(f"Research steps: {result.reasoning_steps}")
  586. print(f"Execution time: {result.execution_time:.2f}s")
  587. # Run the research
  588. asyncio.run(main())
  589. ```
  590. ### As an MCP Server
  591. Two transports are supported: stdio (default) and HTTP streaming.
  592. ```bash
  593. # 1) stdio (default) — for editors/CLIs that spawn a local process
  594. uv run deep-research-mcp
  595. # 2) HTTP streaming — start a local HTTP MCP server
  596. uv run deep-research-mcp --transport http --host 127.0.0.1 --port 8080
  597. ```
  598. Notes:
  599. - HTTP mode uses streaming responses provided by FastMCP. The tools in this
  600. server return their full results when a research task completes; streaming is
  601. still beneficial for compatible clients and for future incremental outputs.
  602. - The verified Streamable HTTP endpoint is `/mcp`, so the default local URL is
  603. `http://127.0.0.1:8080/mcp`.
  604. - If you start the server outside the client and rely on environment variables
  605. for credentials, export them before launching the server process. If you use
  606. `stdio` and let the client spawn the server, make sure the client passes the
  607. required env vars through.
  608. - The server exposes three tools: `deep_research` (with an optional `backend`
  609. argument naming a `[backends.<name>]` table from `~/.deep_research`),
  610. `research_status`, and `list_backends`, which returns structured backend
  611. metadata and credential-presence flags (see below). Named
  612. backends require the TOML file; an environment-only deployment exposes just
  613. the default backend. Task IDs are returned as `<backend>:<id>`.
  614. #### Research and status output
  615. `deep_research` and `research_status` return JSON objects directly in MCP
  616. `structuredContent`, with matching SDK-generated JSON text in `content`.
  617. - `deep_research`: `status`, `task_id`, `final_report`, `citations` (each with
  618. `index`, `title`, `url`), `reasoning_steps`, `search_queries`, `total_steps`,
  619. `message`, `error_code`, and `execution_time`.
  620. - `research_status`: `task_id`, `status`, `created_at`, `completed_at`, `message`,
  621. `error`, and `result`. `result` is `null` unless a completed report is recovered;
  622. then it contains the full research object. A recovery exception preserves the
  623. provider status and sets `error`; completion alone does not guarantee recovery.
  624. Available task IDs use `<backend>:<id>`; providers receive raw IDs. A research
  625. result without an ID has `task_id: null`. If initialization prevents routing,
  626. status errors retain the supplied ID. Timestamps retain provider-specific values.
  627. Inspect `status`, `message`/`error`, and `error_code` for failures, not prose
  628. prefixes or only MCP's `isError` flag.
  629. Migration: read the object directly, without a string-valued `result` wrapper.
  630. Report text is in `final_report` (or `result.final_report` after recovery).
  631. Provider-written Markdown is unchanged; MCP-added report formatting is removed.
  632. Restart an already-running server to load the updated implementation and schemas.
  633. #### Backend discovery output
  634. `list_backends()` takes no arguments and returns an object with a `backends`
  635. array and an `error` field. The MCP response's `structuredContent` contains
  636. that object directly; `content` also contains its JSON text representation for
  637. clients that only read text. The tool advertises an `outputSchema` for this
  638. structure. For example, a configured OpenAI backend can produce:
  639. ```json
  640. {
  641. "backends": [
  642. {
  643. "name": "default",
  644. "provider": "openai",
  645. "model": "gpt-6.1-sol",
  646. "base_url": "https://api.openai.com/v1",
  647. "api_style": "responses",
  648. "reasoning_effort": "high",
  649. "api_key_present": true,
  650. "oauth_present": null,
  651. "run_options_present": null,
  652. "shared_output_present": null,
  653. "error": null
  654. }
  655. ],
  656. "error": null
  657. }
  658. ```
  659. The default entry comes first, followed by named backends in configuration order.
  660. `api_style` applies only to the `openai` provider. `reasoning_effort` is the
  661. configured value, or `null` when omitted; it does not infer a model's defaults.
  662. `api_key_present` reports key presence for providers other than `openai-codex`;
  663. that provider uses `oauth_present` to report whether its auth file exists.
  664. Gnosis additionally reports `run_options_present` and `shared_output_present`.
  665. Inapplicable flags are `null`. Local services may not require an API key, and
  666. presence does not prove valid credentials, model access, or service health.
  667. API keys, OAuth tokens, and Gnosis file contents are never included.
  668. A failure to read or enumerate the configuration returns an empty `backends`
  669. array and a top-level `error`. A backend that cannot be loaded remains in the
  670. array with its `name` and `error`; its other fields are `null`, and other
  671. backends are still listed. Successful error fields are `null`.
  672. This replaces the previous newline-delimited text return value. Clients should
  673. read `result.structuredContent["backends"]`; text-only clients can JSON-decode
  674. the text content instead of parsing the old lines.
  675. #### OAuth authentication for HTTP
  676. HTTP OAuth is opt-in. Set both variables below before starting the server:
  677. ```bash
  678. export MCP_AUTH_ISSUER_URL="https://firm-mermaid-02-staging.authkit.app"
  679. export MCP_AUTH_RESOURCE_URL="http://127.0.0.1:8080/mcp"
  680. uv run deep-research-mcp --transport http --host 127.0.0.1 --port 8080
  681. ```
  682. `MCP_AUTH_RESOURCE_URL` must exactly match the Resource Indicator configured in
  683. WorkOS, including the `/mcp` path. When enabled, the server verifies each
  684. AuthKit access token's signature, issuer, expiration, and audience and publishes
  685. RFC 9728 protected-resource metadata for MCP clients. No WorkOS API key or
  686. client secret is required by the server. Local `stdio` usage is unchanged.
  687. In WorkOS, enable Client ID Metadata Documents (CIMD), keep Dynamic Client
  688. Registration (DCR) enabled for older clients, and add the resource URL under
  689. Connect → Configuration. See the [WorkOS MCP authentication
  690. guide](https://workos.com/docs/authkit/mcp).
  691. ### Command-Line Interface
  692. The installed `deep-research-cli` command provides direct access to all
  693. research functionality from the terminal. Its implementation lives in
  694. `src/deep_research_mcp/cli.py`, while `cli/deep-research-cli.py` remains a
  695. source-checkout compatibility wrapper. It supports two modes of operation:
  696. **agent mode** (default) which runs `DeepResearchAgent` directly, and **MCP
  697. client mode** which connects to a running MCP server over HTTP.
  698. Configuration is loaded from `~/.deep_research` by default. Every
  699. `ResearchConfig` parameter can be overridden via CLI flags, which take
  700. precedence over both the TOML file and environment variables. Pass
  701. `--backend NAME` to use a named `[backends.NAME]` table instead. The `status`
  702. command accepts task IDs in the `<backend>:<id>` form returned by the MCP
  703. server and routes them to the named backend automatically.
  704. ### Terminal UI
  705. The repository also ships with a full-screen terminal UI at
  706. `cli/deep-research-tui.py`. It presents the same core functionality as the
  707. CLI in a dark, keyboard-driven interface for running deep research, task status
  708. checks, and saving output to disk.
  709. ![Deep Research TUI Demo](docs/images/tui-demo.gif)
  710. The TUI features a split-panel layout:
  711. - **Left panel**: Configuration controls for mode selection (Agent/MCP), provider settings, model configuration, query input, and system prompt
  712. - **Right panel**: Output display showing research results or status information
  713. The animation above demonstrates the TUI workflow: loading a research query,
  714. running it through a local Dr Tulu-compatible demo endpoint, viewing the result
  715. in the output panel, and saving the output to a file.
  716. #### Quick Start
  717. ```bash
  718. # Start in direct agent mode
  719. uv run python cli/deep-research-tui.py
  720. # Start in MCP client mode
  721. uv run python cli/deep-research-tui.py --mode mcp \
  722. --server-url http://127.0.0.1:8080/mcp
  723. # Start with Gemini selected
  724. uv run python cli/deep-research-tui.py --provider gemini
  725. # Start on a named backend from ~/.deep_research
  726. uv run python cli/deep-research-tui.py --backend tavily
  727. ```
  728. With `--backend`, the form is pre-filled from that `[backends.<name>]` table.
  729. Its provider, API style and credentials are fixed, so those controls are
  730. disabled; model, endpoint and reasoning effort can still be edited. In MCP
  731. mode the backend name is sent to the server, and a raw task ID is sent as
  732. `<backend>:<id>` so the server routes it to that backend. Task IDs that
  733. already carry a `<backend>:` prefix are routed to that backend when checking
  734. status in either mode.
  735. #### TUI Workflow
  736. - Use the left control panel to edit provider settings, query text, system prompt, and save path.
  737. - The TUI starts focused on the `Mode` selector rather than inside the query editor.
  738. - Use `Tab` / `Shift+Tab` to move through all controls.
  739. - Use `Up` / `Down` to move between non-editor controls, including single-line inputs.
  740. - Use `Left` / `Right` to toggle booleans and cycle through choice fields when a `Switch` or `Select` has focus.
  741. - Press `Enter` to activate buttons, toggle switches, cycle selects, or move forward from a single-line input.
  742. - `TextArea` widgets such as `Query` and `System Prompt` keep normal cursor-key editing behavior.
  743. - Use `r` to run deep research, `t` to check task status, `s` to save the current output, and `q` to quit.
  744. - The right panel shows the latest research report or status response.
  745. #### Provider Defaults
  746. In `agent` mode, the TUI applies provider-aware defaults:
  747. - `openai` + `responses`: model `gpt-6.1-sol`, base URL `https://api.openai.com/v1`
  748. - `openai` + `chat_completions`: model `gpt-6-luna`, base URL `https://api.openai.com/v1`
  749. - `openai-codex`: model `auto`, fixed base URL `https://chatgpt.com/backend-api/codex`
  750. - `dr-tulu`: model `dr-tulu`, base URL `http://localhost:8080/`
  751. - `gemini`: model `deep-research-preview-04-2026`, base URL `https://generativelanguage.googleapis.com`
  752. - `tavily`: model `mini`, base URL `https://api.tavily.com`
  753. - `gnosis`: logical model `gnosis`, base URL `http://127.0.0.1:8089`; native LLM/search settings and shared output paths come from configuration
  754. Switching provider or OpenAI API style automatically refreshes the model and
  755. base URL defaults. You can still override those fields manually afterward.
  756. The Reasoning Effort selector loads the configured value, or Default when
  757. unset; it applies to OpenAI and Codex direct-agent mode.
  758. #### Research and Saving Output
  759. - `Run Deep Research` executes either the direct agent flow or the MCP client flow, depending on the selected mode.
  760. - `Save Output` writes the current contents of the output panel to the configured path, creating parent directories if needed.
  761. #### Notes
  762. - In `mcp` mode, set `MCP Server URL` to a running Streamable HTTP endpoint such as `http://127.0.0.1:8080/mcp`.
  763. - The TUI reuses the same config-loading behavior as `deep-research-cli`, so `~/.deep_research` and any startup overrides still apply.
  764. - Direct-agent formatted reports and the `JSON Output` toggle are unchanged. MCP mode displays and saves the structured research/status object as JSON, including a recovered report under `result`; it does not unwrap that field as report text.
  765. - The current layout is designed for terminals at least 100 columns wide and 28 rows tall.
  766. #### Quick Start
  767. **Gemini Deep Research:**
  768. ```bash
  769. uv run deep-research-cli \
  770. --provider gemini \
  771. --model deep-research-preview-04-2026 \
  772. --base-url https://generativelanguage.googleapis.com \
  773. research "What is the capital of France?"
  774. ```
  775. Expected output (snippet):
  776. ```text
  777. ============================================================
  778. RESEARCH REPORT
  779. ============================================================
  780. Task ID: v1_Chd5YUxjYVpXRUotYWxrZFVQOF9lcTRRVRIX...
  781. Total steps: 1
  782. Execution time: 245.94s
  783. # Comprehensive Analysis of the French Capital: Demographic,
  784. # Economic, and Historical Dimensions of Paris
  785. **Key Points**
  786. * **The capital of France is Paris**, acting as the undisputed
  787. political, economic, and cultural epicenter of the nation.
  788. * Data indicates that the Paris metropolitan area commands a
  789. Gross Domestic Product (GDP) exceeding $1.03 trillion ...
  790. ```
  791. **OpenAI GPT-6 Sol research:**
  792. ```bash
  793. uv run deep-research-cli \
  794. --provider openai \
  795. --model gpt-6.1-sol \
  796. --base-url https://api.openai.com/v1 \
  797. research "What is the capital of France?"
  798. ```
  799. Example output from an earlier model (actual results and task IDs vary):
  800. ```text
  801. ============================================================
  802. RESEARCH REPORT
  803. ============================================================
  804. Task ID: resp_0e55abdae3d3ce390069dca3c7d78c819f91...
  805. Total steps: 22
  806. Search queries: 10
  807. Citations: 1
  808. Execution time: 34.34s
  809. The capital of France is **Paris**
  810. (www.britannica.com/place/Paris)
  811. ============================================================
  812. CITATIONS
  813. ============================================================
  814. 1. Paris | Definition, Map, Population, Facts, & History
  815. https://www.britannica.com/place/Paris
  816. ```
  817. **OpenAI Codex subscription research:**
  818. ```bash
  819. uv run deep-research-cli auth login
  820. uv run deep-research-cli \
  821. --provider openai-codex \
  822. research "What is the capital of France?"
  823. ```
  824. **DR-Tulu** (requires a running [dr-tulu](https://github.com/allenai/dr-tulu) service; see [Dr Tulu provider example](#dr-tulu-provider-example)):
  825. ```bash
  826. uv run deep-research-cli \
  827. --provider dr-tulu \
  828. --base-url http://localhost:8080/ \
  829. research "What is the capital of France?"
  830. ```
  831. Expected output:
  832. ```text
  833. ============================================================
  834. RESEARCH REPORT
  835. ============================================================
  836. Task ID: 7f3a1b2c-...
  837. Total steps: 4
  838. Citations: 2
  839. Execution time: 18.72s
  840. The capital of France is Paris. Paris has served as the
  841. French capital since the late 10th century ...
  842. ============================================================
  843. CITATIONS
  844. ============================================================
  845. 1. Source 1
  846. https://en.wikipedia.org/wiki/Paris
  847. 2. Source 2
  848. https://www.britannica.com/place/Paris
  849. ```
  850. View resolved configuration or all available options:
  851. ```bash
  852. uv run deep-research-cli config --pretty
  853. uv run deep-research-cli --help
  854. ```
  855. #### Commands
  856. **`research QUERY`** -- perform deep research on a query.
  857. ```bash
  858. # Simple research (agent mode)
  859. uv run deep-research-cli research "Economic impact of AI adoption"
  860. # Override provider and model for a single run
  861. uv run deep-research-cli --provider gemini research "Climate change policies"
  862. # Use a named backend declared in ~/.deep_research
  863. uv run deep-research-cli --backend tavily research "Climate change policies"
  864. # Override OpenAI reasoning effort for a single run
  865. uv run deep-research-cli --provider openai-codex --model gpt-6-sol \
  866. --reasoning-effort medium research "Climate change policies"
  867. # Use a custom system prompt from a file
  868. uv run deep-research-cli research "Healthcare trends" --system-prompt-file prompts/health.txt
  869. # Or pass the system prompt inline
  870. uv run deep-research-cli research "Healthcare trends" --system-prompt "Focus on peer-reviewed sources only"
  871. # Output as JSON (includes metadata, citations, execution time)
  872. uv run deep-research-cli research "AI safety" --json
  873. # Save the report to a file
  874. uv run deep-research-cli research "Renewable energy" --output-file report.md
  875. # Disable code interpreter / data analysis tools
  876. uv run deep-research-cli research "Simple topic" --no-analysis
  877. # Notify a webhook when research completes
  878. uv run deep-research-cli research "Long query" --callback-url https://example.com/webhook
  879. ```
  880. #### Tested local OpenAI-compatible backends
  881. The unified CLI works with local servers that expose an OpenAI-compatible
  882. Chat Completions API. The commands below were tested against local Ollama and
  883. local `llama-server` (from `llama.cpp`).
  884. ##### Ollama
  885. Basic `research` flow:
  886. ```bash
  887. uv run deep-research-cli \
  888. --provider openai \
  889. --api-style chat_completions \
  890. --base-url http://localhost:11434/v1 \
  891. --api-key test \
  892. --model qwen3.5:0.8b \
  893. --timeout 180 \
  894. research "Reply with exactly: ok"
  895. ```
  896. Observed output:
  897. ```text
  898. HTTP Request: POST http://localhost:11434/v1/chat/completions "HTTP/1.1 200 OK"
  899. ============================================================
  900. RESEARCH REPORT
  901. ============================================================
  902. Task ID: chatcmpl-215
  903. Total steps: 1
  904. Execution time: 14.33s
  905. ok
  906. ```
  907. ##### llama-server
  908. Start a local OpenAI-compatible server and let it download a small GGUF model
  909. from Hugging Face automatically:
  910. ```bash
  911. llama-server \
  912. --host 127.0.0.1 \
  913. --port 8081 \
  914. --api-key test \
  915. --ctx-size 4096 \
  916. --alias qwen2.5-0.5b \
  917. -hf Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M
  918. ```
  919. Then point the CLI at the server:
  920. ```bash
  921. uv run deep-research-cli \
  922. --provider openai \
  923. --api-style chat_completions \
  924. --base-url http://127.0.0.1:8081/v1 \
  925. --api-key test \
  926. --model qwen2.5-0.5b \
  927. --timeout 120 \
  928. research "Reply with exactly: ok"
  929. ```
  930. Observed output:
  931. ```text
  932. HTTP Request: POST http://127.0.0.1:8081/v1/chat/completions "HTTP/1.1 200 OK"
  933. ============================================================
  934. RESEARCH REPORT
  935. ============================================================
  936. Task ID: chatcmpl-uzqSNDzRgYchZRxn1Kq2MNYyc2w6hpc6
  937. Total steps: 1
  938. Execution time: 0.15s
  939. Ok
  940. ```
  941. **`research QUERY --server-url URL`** -- use MCP client mode.
  942. Instead of running the agent directly, connect to a running Deep Research MCP
  943. server over Streamable HTTP. Both `research` and `status` display JSON in MCP
  944. mode without requiring `--json`; `research --output-file` saves that JSON object.
  945. Direct-agent mode keeps its formatted reports and optional `--json` output.
  946. ```bash
  947. # First, start the MCP server in another terminal:
  948. uv run deep-research-mcp --transport http --host 127.0.0.1 --port 8080
  949. # Then run queries against it:
  950. uv run deep-research-cli research "AI trends" \
  951. --server-url http://127.0.0.1:8080/mcp --output-file research.json
  952. ```
  953. **`status TASK_ID`** -- check the status of a running research task.
  954. ```bash
  955. # Agent mode
  956. uv run deep-research-cli status abc123-def456-ghi789
  957. # MCP client mode
  958. uv run deep-research-cli status abc123-def456-ghi789 \
  959. --server-url http://127.0.0.1:8080/mcp
  960. # A task ID copied from MCP output carries a <backend>: prefix that selects
  961. # the backend; a raw ID uses --backend, or the default without it
  962. uv run deep-research-cli status openai:resp_0e55abdae3d3ce39
  963. ```
  964. **`config`** -- display the resolved configuration.
  965. Shows the final configuration after merging the TOML file, environment
  966. variables, and any CLI overrides.
  967. ```bash
  968. # JSON output (default), with secrets masked
  969. uv run deep-research-cli config
  970. # Human-readable output
  971. uv run deep-research-cli config --pretty
  972. # Show full API keys
  973. uv run deep-research-cli config --pretty --show-secrets
  974. # See the effect of CLI overrides
  975. uv run deep-research-cli --provider gemini --timeout 600 config --pretty
  976. # Skip config validation
  977. uv run deep-research-cli config --no-validate
  978. ```
  979. **`auth {login,status,logout}`** -- manage the independent OpenAI Codex
  980. subscription session.
  981. ```bash
  982. uv run deep-research-cli auth login
  983. uv run deep-research-cli auth status
  984. uv run deep-research-cli auth logout
  985. ```
  986. #### Configuration Overrides
  987. All global flags are placed **before** the subcommand and override the
  988. corresponding `ResearchConfig` field:
  989. | Flag | Description |
  990. |------|-------------|
  991. | `--config PATH` | Path to TOML config file (default: `~/.deep_research`) |
  992. | `--backend NAME` | Use a named `[backends.NAME]` table instead of `[research]`. Cannot be combined with `--provider`, `--model`, `--reasoning-effort`, `--api-key`, `--base-url` or `--api-style`; runtime flags such as `--timeout` still apply. In MCP client mode the name is passed to the server, and `status` sends a raw task ID as `NAME:<id>` so the server routes it to that backend. |
  993. | `--provider {openai,openai-codex,dr-tulu,gemini,tavily,gnosis}` | Research provider |
  994. | `--model MODEL` | Model or agent ID |
  995. | `--reasoning-effort {none,low,medium,high,xhigh,max}` | OpenAI reasoning effort; omit for provider/model default |
  996. | `--api-key KEY` | Provider API key |
  997. | `--base-url URL` | Provider API base URL |
  998. | `--gnosis-config-path PATH` | Native Gnosis request-options JSON; cannot be combined with `--backend` |
  999. | `--gnosis-output-dir PATH` | Shared Gnosis output directory; cannot be combined with `--backend` |
  1000. | `--api-style {responses,chat_completions}` | OpenAI API style |
  1001. | `--timeout SECONDS` | Max research timeout |
  1002. | `--poll-interval SECONDS` | Task poll interval |
  1003. | `--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}` | Logging level |
  1004. | `--enable-reasoning-summaries` | Enable reasoning summaries |
  1005. Configuration precedence (highest to lowest): CLI flags > environment
  1006. variables > TOML config file (`~/.deep_research`) > built-in defaults.
  1007. #### Exit Codes
  1008. | Code | Meaning |
  1009. |------|---------|
  1010. | 0 | Success |
  1011. | 1 | Research or configuration error |
  1012. | 2 | MCP tool error |
  1013. | 3 | Unexpected error |
  1014. ### Example Queries
  1015. ```python
  1016. # Basic research query
  1017. result = await agent.research("Explain the transformer architecture in AI")
  1018. # Research with code analysis
  1019. result = await agent.research(
  1020. query="Analyze global temperature trends over the last 50 years",
  1021. include_code_interpreter=True
  1022. )
  1023. # Custom system instructions
  1024. result = await agent.research(
  1025. query="Review the safety considerations for AGI development",
  1026. system_prompt="""
  1027. Provide a balanced analysis including:
  1028. - Technical challenges
  1029. - Current safety research
  1030. - Regulatory approaches
  1031. - Industry perspectives
  1032. Include specific examples and data where available.
  1033. """
  1034. )
  1035. ```
  1036. ## API Reference
  1037. ### DeepResearchAgent
  1038. The main class for performing research operations.
  1039. #### Methods
  1040. - `research(query, system_prompt=None, include_code_interpreter=True, callback_url=None)`
  1041. - Performs deep research on a query
  1042. - `callback_url`: optional webhook notified when research completes
  1043. - Returns: Dictionary with final report, citations, and metadata
  1044. - `get_task_status(task_id)`
  1045. - Check the status of a research task
  1046. - Returns: Task status information
  1047. ### ResearchConfig
  1048. Configuration class for the research agent.
  1049. #### Parameters
  1050. - `provider`: Research provider (`openai`, `openai-codex`, `dr-tulu`, `gemini`, `tavily`, or `gnosis`; default: `openai`)
  1051. - `api_style`: API style for the `openai` provider (`responses` or `chat_completions`; default: `responses`). Ignored for other providers.
  1052. - `model`: Model identifier
  1053. - OpenAI: Responses model (e.g., `gpt-6.1-sol`)
  1054. - OpenAI Codex subscription: `auto` (default) or an account catalogue slug
  1055. - Dr Tulu: logical provider id (default: `dr-tulu`)
  1056. - Gemini: Deep Research agent id (for example `deep-research-preview-04-2026`)
  1057. - Tavily: Research model (`mini`, `pro`, or `auto`; default: `mini`)
  1058. - Gnosis: logical provider label (default: `gnosis`); the actual LLM model is set in the native request-options JSON
  1059. - `reasoning_effort`: Optional OpenAI reasoning effort (`none`, `low`, `medium`, `high`, `xhigh`, or `max`); model support varies.
  1060. - `api_key`: API key for the configured endpoint (optional). Defaults to env `OPENAI_API_KEY` for `openai`, `DR_TULU_API_KEY` for `dr-tulu`, `GEMINI_API_KEY` / `GOOGLE_API_KEY` for `gemini`, `TAVILY_API_KEY` for `tavily`, and `GNOSIS_API_KEY` for Gnosis service authentication. Ignored for `openai-codex`.
  1061. - `base_url`: Provider API base URL (optional). Defaults to `https://api.openai.com/v1` for `openai`, the fixed `https://chatgpt.com/backend-api/codex` endpoint for `openai-codex`, `http://localhost:8080/` for `dr-tulu`, `https://generativelanguage.googleapis.com` for `gemini`, `https://api.tavily.com` for `tavily`, and `http://127.0.0.1:8089` for `gnosis`.
  1062. - `timeout`: Maximum time for research in seconds (default: 1800)
  1063. - `poll_interval`: Polling interval in seconds (default: 30)
  1064. - `gnosis_config_path`: Path to private native Gnosis `/runs` JSON options; required for new Gnosis research
  1065. - `gnosis_output_dir`: Shared Gnosis output directory; required to recover full Gnosis answers
  1066. ## Development
  1067. ### Running Tests
  1068. ```bash
  1069. # Install dev dependencies
  1070. uv sync --extra dev
  1071. # Run all tests
  1072. uv run pytest -v
  1073. # Run with coverage
  1074. uv run pytest --cov=deep_research_mcp tests/
  1075. # Run specific test file
  1076. uv run pytest tests/test_agents.py
  1077. ```
  1078. When `~/.deep_research_auth.json` contains a current or refreshable
  1079. `openai-codex` session, a normal `uv run pytest tests/` run automatically
  1080. executes the live Codex end-to-end test and consumes subscription allowance.
  1081. Without that session, the test is skipped. Use `-m "not api"` to exclude all
  1082. live provider tests explicitly.
  1083. The Gnosis live test is separately opt-in: set `GNOSIS_TEST_CONFIG_PATH` to the
  1084. private native options file and `GNOSIS_TEST_OUTPUT_DIR` to the shared output
  1085. directory, then run `uv run pytest tests/test_gnosis_backend.py -m api`. It
  1086. starts real research and consumes the configured LLM/search allowance. Set
  1087. `GNOSIS_TEST_BASE_URL` to override the default run endpoint; with `-m "not api"`
  1088. that variable enables only the read-only unknown-run service check.
  1089. ### Lint, Format, Type Check
  1090. ```bash
  1091. uv run black .
  1092. uv run pylint src/deep_research_mcp tests
  1093. uv run mypy src/deep_research_mcp
  1094. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.