duckduckgo-mcp-server-py by southern-dust - MCP Server

DuckDuckGo MCP Server Python Implementation

项目概述 / Project Overview

这是一个功能完整的 DuckDuckGo 搜索 MCP (Model Context Protocol) 服务器的 Python 实现，支持多种传输方式和生产级部署配置。

This is a comprehensive Python implementation of a DuckDuckGo Search MCP (Model Context Protocol) server with multi-transport support and production-ready deployment configurations.

✨ 主要特性 / Key Features

🔍 DuckDuckGo 搜索集成 / DuckDuckGo Search Integration: 无需 API 密钥的 Web 搜索功能 / Web search functionality without API keys
🚀 多传输协议支持 / Multi-Transport Support: STDIO, HTTP, SSE, and Hybrid modes
🐳 Docker 部署就绪 / Docker Ready: 完整的容器化部署方案 / Complete containerized deployment solution
🛡️ 速率限制 / Rate Limiting: 内置的智能速率控制 / Built-in intelligent rate control
🔄 高可用性 / High Availability: 优雅降级和错误恢复机制 / Graceful degradation and error recovery
📊 监控就绪 / Monitoring Ready: 健康检查和状态监控端点 / Health checks and status monitoring endpoints

Transport Modes

1. STDIO Transport

Use Case: Direct integration with MCP clients (like Claude Desktop)
Command Line: duckduckgo-mcp-server --transport stdio
Docker Profile: stdio

2. HTTP Transport

Use Case: REST API integration, web applications
Endpoint: POST /mcp
Port: 8080
Docker Profile: http

3. SSE Transport

Use Case: Real-time web applications, event-driven architectures
Endpoints: GET /sse, POST /sse/request
Port: 8081
Docker Profile: sse

4. Hybrid Mode

Use Case: Production deployments needing multiple transport options
Ports: 8080 (HTTP), 8081 (SSE)
Docker Profile: hybrid, production

Quick Start

Using Docker Compose

STDIO Transport (for local development):
```
docker-compose --profile stdio up
```
HTTP Transport:
```
docker-compose --profile http up
```
SSE Transport:
```
docker-compose --profile sse up
```
Hybrid Mode (recommended for production):
```
docker-compose --profile production up
```

Local Development

Install dependencies:
```
pip install -e .
```

Run with different transports:

# STDIO (default)
python -m duckduckgo_mcp_server.server

# HTTP
python -m duckduckgo_mcp_server.server --transport http

# SSE
python -m duckduckgo_mcp_server.server --transport sse

# Hybrid (all transports)
python -m duckduckgo_mcp_server.server --transport hybrid

API Usage

Tool Schema

The server provides one tool: duckduckgo_web_search

Parameters:

query (required, string): Search query (max 400 characters)
count (optional, integer): Number of results (1-20, default 10)
safeSearch (optional, string): Safe search level ("strict", "moderate", "off")

Example Requests

HTTP Transport

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "duckduckgo_web_search",
      "arguments": {
        "query": "Python async programming",
        "count": 5,
        "safeSearch": "moderate"
      }
    }
  }'

SSE Transport

# Start SSE connection
curl -N http://localhost:8081/sse

# Make search request
curl -X POST http://localhost:8081/sse/request \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "duckduckgo_web_search",
      "arguments": {
        "query": "Docker containers"
      }
    }
  }'

Claude Desktop Configuration

STDIO Transport (Local)

{
  "mcpServers": {
    "duckduckgo-search": {
      "command": "python",
      "args": [
        "-m", "duckduckgo_mcp_server.server",
        "--transport", "stdio"
      ]
    }
  }
}

HTTP Transport (Remote)

{
  "mcpServers": {
    "duckduckgo-search": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "http://localhost:8080/mcp",
        "-H", "Content-Type: application/json",
        "-d", "@-"
      ]
    }
  }
}

Docker Deployment

Building the Image

docker build -t duckduckgo-mcp-server:latest .

Running with Different Profiles

Development (STDIO only):

docker-compose --profile stdio up duckduckgo-stdio

HTTP API:

docker-compose --profile http up duckduckgo-http

Real-time (SSE):

docker-compose --profile sse up duckduckgo-sse

Production (Hybrid + Nginx):
```
docker-compose --profile production up
```
Enhanced (with Redis):
```
docker-compose --profile enhanced up
```

Health Monitoring

All HTTP/SSE endpoints include health checks:

# HTTP health check
curl http://localhost:8080/health

# SSE health check
curl http://localhost:8081/health

# Nginx health check (production mode)
curl http://localhost/health

Rate Limiting

The server implements rate limiting to prevent abuse:

Per Second: 1 request
Per Month: 15,000 requests
Headers: Rate limit information included in responses

Environment Variables

PYTHONPATH: Python module path (default: /app/src)
LOG_LEVEL: Logging level (default: INFO)
HTTP_HOST: HTTP server host (default: 0.0.0.0)
HTTP_PORT: HTTP server port (default: 8080)
SSE_HOST: SSE server host (default: 0.0.0.0)
SSE_PORT: SSE server port (default: 8081)

Development

Project Structure

src/duckduckgo_mcp_server/
├── __init__.py          # Package initialization
├── server.py            # Main server implementation
├── transports.py        # Transport layer implementations
├── search_client.py     # DuckDuckGo search client
├── rate_limiter.py      # Rate limiting functionality
├── models.py            # Data models
└── config.py            # Configuration settings

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=duckduckgo_mcp_server

Code Quality

# Format code
black src/
isort src/

# Type checking
mypy src/

# Linting
flake8 src/

Production Deployment

Using Nginx Reverse Proxy

The provided Nginx configuration handles:

Load balancing
SSL termination
HTTP/2 support
Proper SSE proxying
Health checks

SSL Setup

Place SSL certificates in ./ssl/ directory:
- cert.pem: SSL certificate
- key.pem: Private key
Update Nginx configuration with your domain

Monitoring

Health endpoints: /health on all services
Logs: Structured logging with configurable levels
Metrics: Rate limiting status available via API

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues and questions:

GitHub Issues: Create an issue
Documentation: Wiki