A
securityF
licenseA
qualityA powerful research assistant that conducts intelligent, iterative research through web searches, analysis, and comprehensive report generation on any topic.
Last updated -
4
23
Uses .env files for managing API keys and configuration variables
Integrates with GitHub repositories, including cloning from GitHub URLs as demonstrated in the installation instructions
Converts various file formats to Markdown through the mdconvert.py utility
Leverages OpenAI's API for agent capabilities, requiring an API key for authentication
Provides YouTube transcript retrieval capabilities as part of its research functionality
Deep Research MCP Server
Deep Research is an agent-based tool that provides web search and advanced research capabilities. It leverages HuggingFace's smolagents and is implemented as an MCP server.
This project is based on HuggingFace's open_deep_research example.
Features
Web search and information gathering
PDF and document analysis
Image analysis and description
YouTube transcript retrieval
Archive site search
Requirements
Python 3.11 or higher
uvpackage managerThe following API keys:
OpenAI API key
HuggingFace token
SerpAPI key
Installation
Clone the repository:
git clone https://github.com/Hajime-Y/deep-research-mcp.git
cd deep-research-mcp
Create a virtual environment and install dependencies:
uv venv
source .venv/bin/activate # For Linux or Mac
# .venv\Scripts\activate # For Windows
uv sync
Environment Variables
Create a .env file in the root directory of the project and set the following environment variables:
OPENAI_API_KEY=your_openai_api_key
HF_TOKEN=your_huggingface_token
SERPER_API_KEY=your_serper_api_key
You can obtain a SERPER_API_KEY by signing up at Serper.dev.
Usage
Start the MCP server:
uv run deep_research.py
This will launch the deep_research agent as an MCP server.
Docker Usage
You can also run this MCP server in a Docker container:
# Build the Docker image
docker build -t deep-research-mcp .
# Run with required API keys
docker run -p 8080:8080 \
-e OPENAI_API_KEY=your_openai_api_key \
-e HF_TOKEN=your_huggingface_token \
-e SERPER_API_KEY=your_serper_api_key \
deep-research-mcp
Registering with MCP Clients
To register this Docker container as an MCP server in different clients:
Claude Desktop
Add the following to your Claude Desktop configuration file (typically located at ~/.config/Claude/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"deep-research-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "OPENAI_API_KEY=your_openai_api_key",
"-e", "HF_TOKEN=your_huggingface_token",
"-e", "SERPER_API_KEY=your_serper_api_key",
"deep-research-mcp"
]
}
}
}
Cursor IDE
For Cursor IDE, add the following configuration:
{
"mcpServers": {
"deep-research-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "OPENAI_API_KEY=your_openai_api_key",
"-e", "HF_TOKEN=your_huggingface_token",
"-e", "SERPER_API_KEY=your_serper_api_key",
"deep-research-mcp"
]
}
}
}
Using with Remote MCP Server
If you're running the MCP server on a remote machine or exposing it as a service, you can use the URL-based configuration:
{
"mcpServers": {
"deep-research-mcp": {
"url": "http://your-server-address:8080/mcp",
"type": "sse"
}
}
}
Key Components
deep_research.py: Entry point for the MCP servercreate_agent.py: Agent creation and configurationscripts/: Various tools and utilitiestext_web_browser.py: Text-based web browsertext_inspector_tool.py: File inspection toolvisual_qa.py: Image analysis toolmdconvert.py: Converts various file formats to Markdown
License
This project is provided under the Apache License 2.0.
Acknowledgements
This project uses code from HuggingFace's smolagents and Microsoft's autogen projects.
This server cannot be installed
Related Resources
Related MCP Servers
- -security-license-qualityEnables searching for AI agents by keywords or categories, allowing users to discover tools like coding agents, GUI agents, or industry-specific assistants across marketplaces.Last updated -41
- -securityFlicense-qualityAn AI-focused search engine that enables AI applications to access high-quality knowledge from billions of webpages and ecosystem content sources across various domains including weather, news, encyclopedia, medical information, train tickets, and images.Last updated -30
- AsecurityAlicenseAqualityA sophisticated research assistant that orchestrates a 5-step workflow of connected AI agents to provide deep research capabilities including question enhancement, web search, summarization, citation formatting, and result combination.Last updated -11MIT License