DuckDuckGo

You run a lightweight MCP server that lets you search the web using DuckDuckGo and fetch web content converted to markdown or JSON. It is designed to be easy to talk to from MCP clients, supports safe search controls, and can deliver results in formats friendly for large language models.

How to use

Start the server in STDIO mode to communicate with MCP clients. Run duckduckgo-mcp serve to start, and add --debug if you want verbose logging for troubleshooting. Once running, you can perform searches and fetch content through your MCP client by invoking the provided tools.

Typical usage patterns include: 1) Searching DuckDuckGo for concise results, which returns either JSON data or a text-friendly format suitable for LLMs. 2) Fetching a URL to convert its content to markdown or JSON, with optional length limits and the ability to include image alt text.

How to install

Prerequisites you need before installing: 3) Python 3.10 or higher. 2) uv (recommended) or pip for running Python packages.

Install the DuckDuckGo MCP Server from PyPI (recommended method): 1) Ensure you have uv available or use pip. 2) Install the package.

# Using uv (recommended)
uv pip install duckduckgo-mcp

# Or using pip
pip install duckduckgo-mcp

Alternative installation via UVX for Claude Desktop environments: 1) Install UVX if you haven’t already. 2) Install the DuckDuckGo MCP package via UVX.

# Install UVX if you haven't already
pip install uvx

# Install the DuckDuckGo MCP package
uvx install duckduckgo-mcp

If you want to integrate this MCP server with Claude Desktop or other clients via a local setup, you can install through package managers or run from source. The following commands show typical installation paths. Use the flow that matches your environment.

# Install from source (for development or latest changes)
# Clone the repository
git clone https://github.com/CyranoB/duckduckgo-mcp.git
cd duckduckgo-mcp

# Install with uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .

To run directly from a container, you can build and run a Docker image, but the MCP client interaction still requires STDIO communication with the server. The image can be started in STDIO mode to interact with MCP clients.

# Build the image (uses the version from the latest git tag)
docker build --build-arg VERSION=$(git describe --tags --abbrev=0 | sed 's/^v//') -t duckduckgo-mcp .

# Run the server in STDIO mode inside a container
docker run -i duckduckgo-mcp

Additional notes

The server exposes two main tools to MCP clients: a web search tool and a fetch tool that uses Jina Reader to convert content. You can start the server and then interact with it through your MCP client to perform searches and fetch content in your preferred format.

If you want to enable detailed logging for debugging, start the server with the --debug flag. For search results, you can choose JSON output for structured data or a text-friendly format for LLM integration. When fetching content, you can choose markdown or json as the output format and optionally limit the content length or include image alt text.

Available tools

duckduckgo_search

Search the web using DuckDuckGo with configurable max results, safesearch, and output format (json or text) for MCP clients.

jina_fetch

Fetch a URL and convert its content to markdown or JSON using Jina Reader, with optional max length and image text inclusion.