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 manager- The 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.