Deep Research

🚀 Deep Research MCP Server

Deep Research is a proxy-based tool that offers 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.

🚀 Quick Start

Deep Research is a proxy - based tool that provides web search and advanced research functions. It uses HuggingFace's smolagents and is implemented as an MCP server.

✨ Features

• Web search and information collection
• PDF and document analysis
• Image analysis and description
• YouTube subtitle retrieval
• Archived website search

📦 Installation

Requirements

• Python 3.11 or higher
• uv package manager
• The following API keys:
  • OpenAI API Key
  • HuggingFace Token
  • SerpAPI Key

Steps

1. Clone the repository:

git clone https://github.com/Hajime-Y/deep-research-mcp.git
cd deep-research-mcp

2. Create a virtual environment and install dependencies:

uv venv
source .venv/bin/activate # Linux or Mac
# .venv\Scripts\activate # Windows
uv sync

💻 Usage Examples

Environment Variables

Create a .env file in the project root directory 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 sign up at Serper.dev to get the SERPER_API_KEY.

Starting the MCP Server

uv run deep_research.py

This will start the deep_research agent as an MCP server.

Using Docker

You can also run this MCP server in a Docker container:

# Build the Docker image
docker build -t deep-research-mcp .

# Run with the 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 in MCP Clients

Claude Desktop

Add the following to your Claude Desktop configuration file (usually 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"
      ]
    }
  }
}

Other Clients

Configure according to the specific client's documentation and ensure all environment variables are set correctly.

🔧 Technical Details

Key Components

• Deep Research: The core agent module responsible for handling search and analysis tasks.
• MCP Server: Used to coordinate and manage communication and task allocation among multiple agents.
• Docker Configuration: Provides containerized deployment support, simplifying the installation and maintenance process.