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 Microsoft's autogen projects and is implemented as an MCP server.

This project is based on HuggingFace's open_deep_research example.

✨ Features

• Web search and information collection
• PDF and document analysis
• Image analysis and description
• YouTube duration retrieval
• Archive website search

📦 Installation

Requirements

• Python 3.11 or higher
• uv package manager
• The following API keys:
  • OpenAI API Key
  • HuggingFace Token
  • SerperAPI 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.

Basic Usage

Start the MCP server:

uv run deep_research.py

This will start the deep_research agent as an MCP server.

Advanced Usage

Run with Docker

You can also run this MCP server via 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

Register 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"
      ]
    }
  }
}

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"
      ]
    }
  }
}

Other Clients

Configure in a similar way according to the documentation of the specific tool.

🔧 Technical Details

Key Components

• DeepResearch: The core module that mainly handles deep search and data analysis.
• MCP Server: Provides RESTful API interfaces to support integration with other systems.
• .env: Stores all necessary environment variables to ensure the normal operation of the program.

📄 License

This project is licensed under the MIT License. Please refer to the license file in the project for specific details.