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, or Chat Completions API for broad provider compatibility) and the open-source Open Deep Research stack (based on smolagents). - Python 3.9+ - OpenAI API access (Responses API models, e.g., o4-mini-deep-research-20
Add this skill
npx mdskills install pminervini/deep-research-mcpProvides comprehensive research capabilities with multiple provider support and detailed configuration options
1# Deep Research MCP23A 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, or Chat Completions API for broad provider compatibility) and the open-source Open Deep Research stack (based on smolagents).45## Prerequisites67- Python 3.9+8- One of:9 - OpenAI API access (Responses API models, e.g., `o4-mini-deep-research-2025-06-26`)10 - Open Deep Research dependencies (installed via `requirements.txt`)11- Claude Code, or any other assistant supporting MCP integration1213## Configuration1415### Configuration File1617Create a `~/.deep_research` file in your home directory using TOML format.1819Common settings:2021```toml22[research] # Core Deep Research functionality23provider = "openai" # Available options: "openai", "open-deep-research" -- defaults to "openai"24api_style = "responses" # "responses" (default) or "chat_completions" -- use "chat_completions" for Perplexity, Groq, Ollama, etc.25model = "o4-mini-deep-research-2025-06-26" # OpenAI: model identifier; ODR: LiteLLM model identifier, e.g., openai/qwen/qwen3-coder-30b26api_key = "sk-your-api-key" # API key, optional27base_url = "https://api.openai.com/v1" # OpenAI: OpenAI-compatible endpoint; ODR: LiteLLM-compatible endpoint, e.g., http://localhost:1234/v12829# Task behavior30timeout = 180031poll_interval = 3032max_retries = 33334# Largely based on https://cookbook.openai.com/examples/deep_research_api/introduction_to_deep_research_api_agents35[clarification] # Optional query clarification component36enable = true37triage_model = "gpt-5-mini"38clarifier_model = "gpt-5-mini"39instruction_builder_model = "gpt-5-mini"40api_key = "sk-your-api-key" # Optional, overrides api_key41base_url = "https://api.openai.com/v1" # Optional, overrides base_url4243[logging]44level = "INFO"45```4647OpenAI provider example:4849```toml50[research]51provider = "openai"52model = "o4-mini-deep-research-2025-06-26" # OpenAI model53api_key = "sk-..." # Defaults to OPENAI_API_KEY54base_url = "https://api.openai.com/v1" # OpenAI-compatible endpoint55timeout = 180056poll_interval = 3057max_retries = 358```5960Perplexity (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:6162```toml63[research]64provider = "openai"65api_style = "chat_completions" # Required for Perplexity (no Responses API)66model = "sonar-deep-research" # Perplexity's Sonar Deep Research67api_key = "ppl-..." # Defaults to OPENAI_API_KEY68base_url = "https://api.perplexity.ai" # Perplexity's OpenAI-compatible endpoint69timeout = 180070max_retries = 371```7273Open Deep Research provider example:7475```toml76[research]77provider = "open-deep-research"78model = "openai/qwen/qwen3-coder-30b" # LiteLLM-compatible model id79base_url = "http://localhost:1234/v1" # LiteLLM-compatible endpoint (local or remote)80api_key = "" # Optional if endpoint requires it81timeout = 180082```8384Ollama (local) provider example:8586```toml87[research]88provider = "openai"89api_style = "chat_completions"90model = "llama3.1" # Any model available in your Ollama instance91base_url = "http://localhost:11434/v1" # Ollama's OpenAI-compatible endpoint92api_key = "" # Not required for local Ollama93timeout = 60094max_retries = 395```9697Generic OpenAI-compatible Chat Completions provider (Groq, Together AI, vLLM, etc.):9899```toml100[research]101provider = "openai"102api_style = "chat_completions"103model = "your-model-name"104api_key = "your-api-key"105base_url = "https://api.your-provider.com/v1"106timeout = 600107max_retries = 3108```109110Optional env variables for Open Deep Research tools:111112- `SERPAPI_API_KEY` or `SERPER_API_KEY`: enable Google-style search113- `HF_TOKEN`: optional, logs into Hugging Face Hub for gated models114115### Claude Code Integration1161171. **Configure MCP Server**118119Add the MCP server using Claude Code's command line:120121```bash122claude mcp add deep-research python /path/to/deep-research-mcp/src/deep_research_mcp/mcp_server.py123```124125Replace `/path/to/deep-research-mcp/` with the actual path to your cloned repository.126127HTTP transport: If your client supports MCP-over-HTTP, you can run this128server in HTTP streaming mode (see "As an MCP Server" below) and configure the129client to connect to `http://127.0.0.1:8080/`. Refer to your client's130documentation for how to add an HTTP MCP server.131132For multi-hour research, raise Claude Code's tool timeout before launching the CLI and rely on incremental status polls:133134```bash135export MCP_TOOL_TIMEOUT=14400000 # 4 hours136claude --mcp-config ./.mcp.json137```138139Kick off work with `deep_research` or `research_with_context`, note the returned job ID, and call `research_status` to stream progress without letting any single tool call stagnate.1401412. **Use in Claude Code**:142 - The research tools will appear in Claude Code's tool palette143 - Simply ask Claude to "research [your topic]" and it will use the Deep Research agent144 - For clarified research, ask Claude to "research [topic] with clarification" to get follow-up questions145146### OpenAI Codex Integration1471481. **Configure MCP Server**149150Add the MCP server configuration to your `~/.codex/config.toml` file:151152```toml153[mcp_servers.deep-research]154command = "python"155args = ["/path/to/deep-research-mcp/src/deep_research_mcp/mcp_server.py"]156startup_timeout_ms = 30000 # 30 seconds for server startup157request_timeout_ms = 7200000 # 2 hours for long-running research tasks158# Alternatively, set tool_timeout_sec when using newer Codex clients159# tool_timeout_sec = 14400.0 # 4 hours for deep research runs160```161162Replace `/path/to/deep-research-mcp/` with the actual path to your cloned repository.163164**Important timeout configuration:**165- `startup_timeout_ms`: Time allowed for the MCP server to start (default: 30000ms / 30 seconds)166- `request_timeout_ms`: Maximum time for research queries to complete (recommended: 7200000ms / 2 hours for comprehensive research)167- `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.168- Kick off research once to capture the job ID, then poll `research_status` so each tool call remains short and avoids hitting client timeouts.169170Without proper timeout configuration, long-running research queries may fail with "request timed out" errors.171172Some environments also support MCP-over-HTTP. If available, run the server in173HTTP mode and configure the client with the base URL (for example,174`http://127.0.0.1:8080/`). Consult the specific client's docs for setup steps.1751762. **Use in OpenAI Codex**:177 - The research tools will be available automatically when you start Codex178 - Ask Codex to "research [your topic]" and it will use the Deep Research MCP server179 - For clarified research, ask for "research [topic] with clarification"180181### Gemini CLI Integration1821831. **Configure MCP Server**184185Add the MCP server using Gemini CLI's built-in command:186187```bash188gemini mcp add deep-research python /path/to/deep-research-mcp/src/deep_research_mcp/mcp_server.py189```190191Or manually add to your `~/.gemini/settings.json` file:192193```json194{195 "mcpServers": {196 "deep-research": {197 "command": "python",198 "args": ["/path/to/deep-research-mcp/src/deep_research_mcp/mcp_server.py"],199 "env": {200 "OPENAI_API_KEY": "$OPENAI_API_KEY"201 }202 }203 }204}205```206207Replace `/path/to/deep-research-mcp/` with the actual path to your cloned repository.2082092. **Use in Gemini CLI**:210 - Start Gemini CLI with `gemini`211 - The research tools will be available automatically212- Ask Gemini to "research [your topic]" and it will use the Deep Research MCP server213- Use `/mcp` command to view server status and available tools214215HTTP transport: If your Gemini environment supports MCP-over-HTTP, you may run216the server with `--transport http` and configure Gemini with the server URL.217218## Usage219220### As a Standalone Python Module221222```python223import asyncio224from deep_research_mcp.agent import DeepResearchAgent225from deep_research_mcp.config import ResearchConfig226227async def main():228 # Initialize configuration229 config = ResearchConfig.from_env()230231 # Create agent232 agent = DeepResearchAgent(config)233234 # Perform research235 result = await agent.research(236 query="What are the latest advances in quantum computing?",237 system_prompt="Focus on practical applications and recent breakthroughs"238 )239240 # Print results241 print(f"Report: {result['final_report']}")242 print(f"Citations: {result['citations']}")243 print(f"Research steps: {result['reasoning_steps']}")244245# Run the research246asyncio.run(main())247```248249### As an MCP Server250251Two transports are supported: stdio (default) and HTTP streaming.252253```bash254# 1) stdio (default) — for editors/CLIs that spawn a local process255python src/deep_research_mcp/mcp_server.py256257# 2) HTTP streaming — start a local HTTP MCP server258python src/deep_research_mcp/mcp_server.py --transport http --host 127.0.0.1 --port 8080259```260261Notes:262- HTTP mode uses streaming responses provided by FastMCP. The tools in this263 server return their full results when a research task completes; streaming is264 still beneficial for compatible clients and for future incremental outputs.265- To use HTTP mode, point your MCP-over-HTTP client at the host/port you chose.266267### Example Queries268269```python270# Basic research query271result = await agent.research("Explain the transformer architecture in AI")272273# Research with code analysis274result = await agent.research(275 query="Analyze global temperature trends over the last 50 years",276 include_code_interpreter=True277)278279# Custom system instructions280result = await agent.research(281 query="Review the safety considerations for AGI development",282 system_prompt="""283 Provide a balanced analysis including:284 - Technical challenges285 - Current safety research286 - Regulatory approaches287 - Industry perspectives288 Include specific examples and data where available.289 """290)291292# With clarification (requires ENABLE_CLARIFICATION=true)293clarification_result = agent.start_clarification("quantum computing applications")294if clarification_result.get("needs_clarification"):295 # Answer questions programmatically or present to user296 answers = ["Hardware applications", "Last 5 years", "Commercial products"]297 agent.add_clarification_answers(clarification_result["session_id"], answers)298 enriched_query = agent.get_enriched_query(clarification_result["session_id"])299 result = await agent.research(enriched_query)300```301302## Clarification Features303304The agent includes an optional clarification system to improve research quality through follow-up questions.305306### Configuration307308Enable clarification in your `~/.deep_research` file:309```toml310[clarification]311enable_clarification = true312triage_model = "gpt-5-mini" # Optional, defaults to gpt-5-mini313clarifier_model = "gpt-5-mini" # Optional, defaults to gpt-5-mini314instruction_builder_model = "gpt-5-mini" # Optional, defaults to gpt-5-mini315clarification_api_key = "sk-your-clarification-api-key-here" # Optional custom API key for clarification models316clarification_base_url = "https://custom-api.example.com/v1" # Optional custom endpoint for clarification models317```318319### Usage Flow3203211. **Start Clarification**:322 ```python323 result = agent.start_clarification("your research query")324 ```3253262. **Check if Questions are Needed**:327 ```python328 if result.get("needs_clarification"):329 questions = result["questions"]330 session_id = result["session_id"]331 ```3323333. **Provide Answers**:334 ```python335 answers = ["answer1", "answer2", "answer3"]336 agent.add_clarification_answers(session_id, answers)337 ```3383394. **Get Enriched Query**:340 ```python341 enriched_query = agent.get_enriched_query(session_id)342 final_result = await agent.research(enriched_query)343 ```344345### Integration with AI Assistants346347When using with AI Assistants via MCP tools:3483491. **Request Clarification**: Use `deep_research()` with `request_clarification=True`3502. **Answer Questions**: The AI Assistant will present questions to you3513. **Deep Research**: The AI Asssitant will automatically use `research_with_context()` with your answers352353## API Reference354355### DeepResearchAgent356357The main class for performing research operations.358359#### Methods360361- `research(query, system_prompt=None, include_code_interpreter=True, callback_url=None)`362 - Performs deep research on a query363 - Returns: Dictionary with final report, citations, and metadata364365- `get_task_status(task_id)`366 - Check the status of a research task367 - Returns: Task status information368369- `start_clarification(query)`370 - Analyze query and generate clarifying questions if needed371 - Returns: Dictionary with questions and session ID372373- `add_clarification_answers(session_id, answers)`374 - Add answers to clarification questions375 - Returns: Session status information376377- `get_enriched_query(session_id)`378 - Generate enriched query from clarification session379 - Returns: Enhanced query string380381### ResearchConfig382383Configuration class for the research agent.384385#### Parameters386387- `provider`: Research provider (`openai` or `open-deep-research`; default: `openai`)388- `api_style`: API style for the `openai` provider (`responses` or `chat_completions`; default: `responses`). Use `chat_completions` for Perplexity, Groq, Ollama, and other OpenAI-compatible providers.389- `model`: Model identifier390 - OpenAI: Responses model (e.g., `gpt-5-mini`)391 - Open Deep Research: LiteLLM model id (e.g., `openai/qwen/qwen3-coder-30b`)392- `api_key`: API key for the configured endpoint (optional). Defaults to env `OPENAI_API_KEY`.393- `base_url`: OpenAI-compatible API base URL (optional). Defaults to env `OPENAI_BASE_URL`.394- `timeout`: Maximum time for research in seconds (default: 1800)395- `poll_interval`: Polling interval in seconds (default: 30)396- `max_retries`: Maximum retry attempts (default: 3)397- `enable_clarification`: Enable clarifying questions (default: False)398- `triage_model`: Model for query analysis (default: `gpt-5-mini`)399- `clarifier_model`: Model for query enrichment (default: `gpt-5-mini`)400- `clarification_api_key`: Custom API key for clarification models (optional, defaults to `api_key`)401- `clarification_base_url`: Custom OpenAI-compatible endpoint for clarification models (optional, defaults to `base_url`)402403## Development404405### Running Tests406407```bash408# Run all tests409pytest410411# Run with coverage412pytest --cov=deep-research-mcp tests/413414# Run specific test file415pytest tests/test_agent.py416```417
Full transparency — inspect the skill content before installing.