coderguy-21/mcp-ddg-py

mcp-ddg-py

A minimal, robust MCP server using FastMCP, with DuckDuckGo search and web content fetch tools. Designed for clarity, modularity, and developer experience.

Features

• DuckDuckGo Search Tool: Query DuckDuckGo, filter by date, and get structured results (title, keywords, summary, URL).
• Fetch Tool: Fetch and summarize the content of any URL, extracting title, keywords, summary, and main text.
• Preferred Sites: Custom site boosting via preferred_sites.json for domain-prioritized search.
• CORS Support: HTTP server includes CORS middleware for easy web integration.
• Debug Mode: Global debug flag for extra diagnostic output.
• Clean Shutdown: Suppresses noisy tracebacks on Ctrl-C.

Setup

1. Install uv:

   pip install uv
   

2. Create and activate a virtual environment:

   uv venv .venv
   source .venv/Scripts/activate  # On Windows Bash
   

3. Install dependencies:

uv sync
# or, for editable install:
uv pip install .

Running the Server

Stdio mode (default):

python server.py

HTTP mode:

python server.py --http

Enable debug output:

python server.py --debug

Combine flags:

python server.py http debug

Command-Line Flags

• --http / -http / http: Run as HTTP server (default is stdio)
• --debug / -debug / debug: Enable debug output (prints extra info to console)

Tools

Search Tool

• Function: Search DuckDuckGo for a query, with optional max results and date filter.
• Parameters:
  • query (str): Search query
  • max_hits (int, default 10): Max results
  • date (str, default "any"): Date filter (d, w, m, y, any)
• Returns: List of dicts with title, keywords, summary, url

Fetch Tool

• Function: Fetch and summarize a web page by URL.
• Parameters:
  • url (str): The URL to fetch
• Returns: Dict with title, keywords, summary, content, url

Preferred Sites

You can boost certain domains in search results by editing preferred_sites.json. This file maps keywords to preferred domains. When a search query contains a keyword, the corresponding site(s) are prioritized in the DuckDuckGo search.

Example preferred_sites.json:

{
  "python": ["realpython.com", "docs.python.org"],
  "ai": ["arxiv.org", "huggingface.co"]
}

Example Usage

Search:

{
  "tool": "search",
  "args": {"query": "python web scraping", "max_hits": 5}
}

Fetch:

{
  "tool": "fetch",
  "args": {"url": "https://realpython.com/python-web-scraping-practical-introduction/"}
}

Project Structure

• server.py — Main FastMCP server entry point, handles CLI flags, CORS, debug, and shutdown
• search_tool.py — DuckDuckGo search tool logic
• fetch_tool.py — URL fetch and summary tool logic
• search_utils.py — Shared logic for summary extraction and preferred sites
• preferred_sites.json — Customizable preferred sites for search
• requirements.txt — Python dependencies
• .gitignore — Clean repo hygiene

Notes

• Debug output is controlled by a single global flag and prints extra info for troubleshooting.
• On Ctrl-C, the server exits cleanly without noisy tracebacks.
• CORS is enabled for all origins in HTTP mode (adjust as needed).

For questions or improvements, open an issue or PR!