aml731/mcp-deep-research repository overview

⁠MCP Deep Research Server

A Model Context Protocol (MCP) server that provides advanced research capabilities through iterative search, analysis, and synthesis. This Docker image enables AI assistants to conduct comprehensive research by automatically refining queries, analyzing results, and generating detailed reports.

⁠Quick Start

⁠Pull the Image

docker pull aml731/mcp-deep-research:latest

⁠Run with Stdio Transport (Default)

docker run -e TAVILY_API_KEY=your-api-key-here \
  aml731/mcp-deep-research:latest

⁠Run with HTTP/SSE Transport

docker run -p 8000:8000 \
  -e TAVILY_API_KEY=your-api-key-here \
  -e MCP_TRANSPORT=http \
  aml731/mcp-deep-research:latest

⁠Features

• Iterative Research: Automatically refines search queries based on results
• Multi-Source Analysis: Analyzes content from multiple sources for quality and complexity
• Intelligent Query Generation: Generates follow-up questions to fill knowledge gaps
• Response Synthesis: Creates comprehensive research reports with confidence scoring
• Rate Limiting & Caching: Built-in optimization for API usage
• Dual Transport Modes: Supports both stdio and HTTP/SSE transports
• Security: Runs as non-root user with minimal attack surface

⁠Environment Variables

⁠Required

⁠Transport Configuration

⁠Search Configuration

⁠Research Configuration

⁠Performance Configuration

⁠Logging Configuration

⁠Usage Examples

⁠Docker Run Command

⁠Stdio Mode (for MCP clients like Claude Desktop)

docker run \
  -e TAVILY_API_KEY=tvly-xxxxxxxxxxxxx \
  -e MCP_TRANSPORT=stdio \
  aml731/mcp-deep-research:latest

⁠HTTP/SSE Mode (for web-based clients like Open Web UI)

docker run -d \
  --name mcp-deep-research \
  -p 8000:8000 \
  -e TAVILY_API_KEY=tvly-xxxxxxxxxxxxx \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_PORT=8000 \
  -e LOG_LEVEL=INFO \
  aml731/mcp-deep-research:latest

⁠With Custom Configuration

docker run -d \
  --name mcp-deep-research \
  -p 8000:8000 \
  -e TAVILY_API_KEY=tvly-xxxxxxxxxxxxx \
  -e MCP_TRANSPORT=http \
  -e DEFAULT_SEARCH_DEPTH=advanced \
  -e MAX_SEARCH_RESULTS=15 \
  -e MAX_ITERATIONS=5 \
  -e CACHE_ENABLED=true \
  -e CACHE_TTL=7200 \
  -e LOG_LEVEL=DEBUG \
  aml731/mcp-deep-research:latest

⁠Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  mcp-deep-research:
    image: aml731/mcp-deep-research:latest
    container_name: mcp-deep-research
    ports:
      - "8000:8000"
    environment:
      # Required
      TAVILY_API_KEY: ${TAVILY_API_KEY}
      
      # Transport Configuration
      MCP_TRANSPORT: http
      MCP_HTTP_HOST: 0.0.0.0
      MCP_HTTP_PORT: 8000
      
      # Search Configuration
      DEFAULT_SEARCH_DEPTH: advanced
      MAX_SEARCH_RESULTS: 10
      SEARCH_TIMEOUT: 30
      
      # Research Configuration
      DEFAULT_CONFIDENCE_THRESHOLD: 0.75
      MAX_ITERATIONS: 3
      
      # Performance Configuration
      RATE_LIMIT_REQUESTS: 10
      CACHE_ENABLED: true
      CACHE_TTL: 3600
      
      # Logging
      LOG_LEVEL: INFO
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import mcp_deep_research"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

Create a .env file with your API key:

TAVILY_API_KEY=tvly-xxxxxxxxxxxxx

Run with Docker Compose:

docker-compose up -d

View logs:

docker-compose logs -f mcp-deep-research

Stop the service:

docker-compose down

⁠Available MCP Tools

The server provides the following tools via the Model Context Protocol:

⁠research

Conduct comprehensive research on a given topic with iterative refinement.

Parameters:

• query (string, required): The research question or topic
• max_iterations (integer, optional): Maximum number of research iterations
• search_depth (string, optional): Search depth - "basic" or "advanced"

⁠quick_search

Perform a quick search with basic analysis.

Parameters:

• query (string, required): Search query
• max_results (integer, optional): Maximum number of results

⁠analyze_sources

Analyze the quality and complexity of search results.

Parameters:

• urls (array, required): List of URLs to analyze

⁠HTTP/SSE Endpoints

When running in HTTP mode, the following endpoints are available:

• GET /sse - Server-Sent Events endpoint for bidirectional MCP communication
• POST /messages - Message endpoint for client requests

⁠Health Check

The container includes a health check that verifies the Python module can be imported:

docker inspect --format='{{.State.Health.Status}}' mcp-deep-research

⁠Security

• Runs as non-root user (mcpuser, UID 1000)
• Multi-stage build for minimal image size
• No unnecessary packages or build tools in final image
• Python bytecode writing disabled for security

⁠Troubleshooting

⁠Container won't start

Check if the Tavily API key is set:

docker logs mcp-deep-research

⁠HTTP mode not accessible

Ensure port 8000 is properly mapped and MCP_TRANSPORT=http is set:

docker run -p 8000:8000 -e MCP_TRANSPORT=http -e TAVILY_API_KEY=your-key aml731/mcp-deep-research:latest

⁠View container logs

docker logs -f mcp-deep-research

⁠Interactive debugging

docker run -it --entrypoint /bin/bash aml731/mcp-deep-research:latest

⁠Image Tags

• latest - Latest stable release
• v0.1.0 - Specific version tags

⁠License

GNU General Public License v3.0 (GPL-3.0) - see LICENSE⁠ for details.

⁠Acknowledgments

• Built with the Model Context Protocol⁠
• Powered by Tavily Search API⁠