Deep Research MCP Server

Integrations

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

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
uv package 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 server
create_agent.py: Agent creation and configuration
scripts/: Various tools and utilities
- text_web_browser.py: Text-based web browser
- text_inspector_tool.py: File inspection tool
- visual_qa.py: Image analysis tool
- mdconvert.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

security - not tested

license - permissive license

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

An agent-based tool that provides web search and advanced research capabilities including document analysis, image description, and YouTube transcript retrieval.

Related MCP Servers

MCP Server Firecrawl
Msparihar
A
security
A
license
A
quality
A server that provides web scraping and intelligent content searching capabilities using the Firecrawl API, enabling AI agents to extract structured data from websites and perform content searches.
Last updated -
5
2
TypeScript
MIT License
MCP Browser Use
janspoerer
-
security
A
license
-
quality
Empowers AI agents to perform web browsing, automation, and scraping tasks with minimal supervision using natural language instructions and Selenium.
Last updated -
1
Python
Apache 2.0
AI Agent Marketplace Index Search
AI-Agent-Hub
-
security
F
license
-
quality
Enables 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 -
21
Python
Bocha Search MCP
BochaAI
-
security
F
license
-
quality
An 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 -
4
Python

View all related MCP servers

Deep Research MCP Server