# Directory Structure
```
├── .github
│ └── workflows
│ └── python-publish.yml
├── .gitignore
├── .python-version
├── Dockerfile
├── LICENSE
├── pyproject.toml
├── README.md
├── smithery.yaml
├── src
│ └── duckduckgo_mcp_server
│ ├── __init__.py
│ └── server.py
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/.python-version:
--------------------------------------------------------------------------------
```
3.13.2
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/_build/
# PyBuilder
.pybuilder/
target/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# pyenv
# For a library or package, you might want to ignore these files since the code is
# intended to run in multiple environments; otherwise, check them in:
# .python-version
# pipenv
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
# However, in case of collaboration, if having platform-specific dependencies or dependencies
# having no cross-platform support, pipenv may install dependencies that don't work, or not
# install all needed dependencies.
#Pipfile.lock
# UV
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
#uv.lock
# poetry
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
#poetry.lock
# pdm
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
# in version control.
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
.pdm.toml
.pdm-python
.pdm-build/
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/
# Celery stuff
celerybeat-schedule
celerybeat.pid
# SageMath parsed files
*.sage.py
# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# mypy
.mypy_cache/
.dmypy.json
dmypy.json
# Pyre type checker
.pyre/
# pytype static type analyzer
.pytype/
# Cython debug symbols
cython_debug/
# PyCharm
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
# and can be added to the global gitignore or merged into this file. For a more nuclear
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/
# PyPI configuration file
.pypirc
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# DuckDuckGo Search MCP Server
[](https://smithery.ai/server/@nickclyde/duckduckgo-mcp-server)
A Model Context Protocol (MCP) server that provides web search capabilities through DuckDuckGo, with additional features for content fetching and parsing.
<a href="https://glama.ai/mcp/servers/phcus2gcpn">
<img width="380" height="200" src="https://glama.ai/mcp/servers/phcus2gcpn/badge" alt="DuckDuckGo Server MCP server" />
</a>
## Features
- **Web Search**: Search DuckDuckGo with advanced rate limiting and result formatting
- **Content Fetching**: Retrieve and parse webpage content with intelligent text extraction
- **Rate Limiting**: Built-in protection against rate limits for both search and content fetching
- **Error Handling**: Comprehensive error handling and logging
- **LLM-Friendly Output**: Results formatted specifically for large language model consumption
## Installation
### Installing via Smithery
To install DuckDuckGo Search Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@nickclyde/duckduckgo-mcp-server):
```bash
npx -y @smithery/cli install @nickclyde/duckduckgo-mcp-server --client claude
```
### Installing via `uv`
Install directly from PyPI using `uv`:
```bash
uv pip install duckduckgo-mcp-server
```
## Usage
### Running with Claude Desktop
1. Download [Claude Desktop](https://claude.ai/download)
2. Create or edit your Claude Desktop configuration:
- On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Add the following configuration:
```json
{
"mcpServers": {
"ddg-search": {
"command": "uvx",
"args": ["duckduckgo-mcp-server"]
}
}
}
```
3. Restart Claude Desktop
### Development
For local development, you can use the MCP CLI:
```bash
# Run with the MCP Inspector
mcp dev server.py
# Install locally for testing with Claude Desktop
mcp install server.py
```
## Available Tools
### 1. Search Tool
```python
async def search(query: str, max_results: int = 10) -> str
```
Performs a web search on DuckDuckGo and returns formatted results.
**Parameters:**
- `query`: Search query string
- `max_results`: Maximum number of results to return (default: 10)
**Returns:**
Formatted string containing search results with titles, URLs, and snippets.
### 2. Content Fetching Tool
```python
async def fetch_content(url: str) -> str
```
Fetches and parses content from a webpage.
**Parameters:**
- `url`: The webpage URL to fetch content from
**Returns:**
Cleaned and formatted text content from the webpage.
## Features in Detail
### Rate Limiting
- Search: Limited to 30 requests per minute
- Content Fetching: Limited to 20 requests per minute
- Automatic queue management and wait times
### Result Processing
- Removes ads and irrelevant content
- Cleans up DuckDuckGo redirect URLs
- Formats results for optimal LLM consumption
- Truncates long content appropriately
### Error Handling
- Comprehensive error catching and reporting
- Detailed logging through MCP context
- Graceful degradation on rate limits or timeouts
## Contributing
Issues and pull requests are welcome! Some areas for potential improvement:
- Additional search parameters (region, language, etc.)
- Enhanced content parsing options
- Caching layer for frequently accessed content
- Additional rate limiting strategies
## License
This project is licensed under the MIT License.
```
--------------------------------------------------------------------------------
/src/duckduckgo_mcp_server/__init__.py:
--------------------------------------------------------------------------------
```python
__version__ = "0.1.1"
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
startCommand:
type: stdio
configSchema:
# JSON Schema defining the configuration options for the MCP.
{}
commandFunction:
# A JS function that produces the CLI command based on the given config to start the MCP on stdio.
|-
(config) => ({ command: 'python', args: ['-m', 'duckduckgo_mcp_server.server'] })
exampleConfig: {}
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
FROM python:3.11-alpine
# Install system dependencies
RUN apk add --no-cache gcc musl-dev linux-headers
# Set working directory
WORKDIR /app
# Copy all files
COPY . /app
# Install Python dependencies
RUN pip install --upgrade pip \
&& pip install --no-cache-dir .
# Expose port if needed (MCP uses stdio, so not required)
# Run the MCP server
CMD ["python", "-m", "duckduckgo_mcp_server.server"]
```
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
```toml
[project]
name = "duckduckgo-mcp-server"
version = "0.1.1"
description = "MCP Server for searching via DuckDuckGo"
readme = "README.md"
authors = [{ name = "Nick Clyde", email = "[email protected]" }]
requires-python = ">=3.10"
dependencies = ["beautifulsoup4>=4.13.3", "httpx>=0.28.1", "mcp[cli]>=1.3.0"]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
]
[project.urls]
Homepage = "https://github.com/nickclyde/duckduckgo-mcp-server"
Issues = "https://github.com/nickclyde/duckduckgo-mcp-server/issues"
[project.scripts]
duckduckgo-mcp-server = "duckduckgo_mcp_server.server:main"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```
--------------------------------------------------------------------------------
/.github/workflows/python-publish.yml:
--------------------------------------------------------------------------------
```yaml
# This workflow will upload a Python Package to PyPI when a release is created
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.
name: Upload Python Package
on:
release:
types: [published]
permissions:
contents: read
jobs:
release-build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.x"
- name: Build release distributions
run: |
# NOTE: put your own distribution build steps here.
python -m pip install build
python -m build
- name: Upload distributions
uses: actions/upload-artifact@v4
with:
name: release-dists
path: dist/
pypi-publish:
runs-on: ubuntu-latest
needs:
- release-build
permissions:
# IMPORTANT: this permission is mandatory for trusted publishing
id-token: write
# Dedicated environments with protections for publishing are strongly recommended.
# For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
environment:
name: pypi
# OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
# url: https://pypi.org/p/YOURPROJECT
#
# ALTERNATIVE: if your GitHub Release name is the PyPI project version string
# ALTERNATIVE: exactly, uncomment the following line instead:
# url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
steps:
- name: Retrieve release distributions
uses: actions/download-artifact@v4
with:
name: release-dists
path: dist/
- name: Publish release distributions to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
with:
packages-dir: dist/
```
--------------------------------------------------------------------------------
/src/duckduckgo_mcp_server/server.py:
--------------------------------------------------------------------------------
```python
from mcp.server.fastmcp import FastMCP, Context
import httpx
from bs4 import BeautifulSoup
from typing import List, Dict, Optional, Any
from dataclasses import dataclass
import urllib.parse
import sys
import traceback
import asyncio
from datetime import datetime, timedelta
import time
import re
@dataclass
class SearchResult:
title: str
link: str
snippet: str
position: int
class RateLimiter:
def __init__(self, requests_per_minute: int = 30):
self.requests_per_minute = requests_per_minute
self.requests = []
async def acquire(self):
now = datetime.now()
# Remove requests older than 1 minute
self.requests = [
req for req in self.requests if now - req < timedelta(minutes=1)
]
if len(self.requests) >= self.requests_per_minute:
# Wait until we can make another request
wait_time = 60 - (now - self.requests[0]).total_seconds()
if wait_time > 0:
await asyncio.sleep(wait_time)
self.requests.append(now)
class DuckDuckGoSearcher:
BASE_URL = "https://html.duckduckgo.com/html"
HEADERS = {
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
}
def __init__(self):
self.rate_limiter = RateLimiter()
def format_results_for_llm(self, results: List[SearchResult]) -> str:
"""Format results in a natural language style that's easier for LLMs to process"""
if not results:
return "No results were found for your search query. This could be due to DuckDuckGo's bot detection or the query returned no matches. Please try rephrasing your search or try again in a few minutes."
output = []
output.append(f"Found {len(results)} search results:\n")
for result in results:
output.append(f"{result.position}. {result.title}")
output.append(f" URL: {result.link}")
output.append(f" Summary: {result.snippet}")
output.append("") # Empty line between results
return "\n".join(output)
async def search(
self, query: str, ctx: Context, max_results: int = 10
) -> List[SearchResult]:
try:
# Apply rate limiting
await self.rate_limiter.acquire()
# Create form data for POST request
data = {
"q": query,
"b": "",
"kl": "",
}
await ctx.info(f"Searching DuckDuckGo for: {query}")
async with httpx.AsyncClient() as client:
response = await client.post(
self.BASE_URL, data=data, headers=self.HEADERS, timeout=30.0
)
response.raise_for_status()
# Parse HTML response
soup = BeautifulSoup(response.text, "html.parser")
if not soup:
await ctx.error("Failed to parse HTML response")
return []
results = []
for result in soup.select(".result"):
title_elem = result.select_one(".result__title")
if not title_elem:
continue
link_elem = title_elem.find("a")
if not link_elem:
continue
title = link_elem.get_text(strip=True)
link = link_elem.get("href", "")
# Skip ad results
if "y.js" in link:
continue
# Clean up DuckDuckGo redirect URLs
if link.startswith("//duckduckgo.com/l/?uddg="):
link = urllib.parse.unquote(link.split("uddg=")[1].split("&")[0])
snippet_elem = result.select_one(".result__snippet")
snippet = snippet_elem.get_text(strip=True) if snippet_elem else ""
results.append(
SearchResult(
title=title,
link=link,
snippet=snippet,
position=len(results) + 1,
)
)
if len(results) >= max_results:
break
await ctx.info(f"Successfully found {len(results)} results")
return results
except httpx.TimeoutException:
await ctx.error("Search request timed out")
return []
except httpx.HTTPError as e:
await ctx.error(f"HTTP error occurred: {str(e)}")
return []
except Exception as e:
await ctx.error(f"Unexpected error during search: {str(e)}")
traceback.print_exc(file=sys.stderr)
return []
class WebContentFetcher:
def __init__(self):
self.rate_limiter = RateLimiter(requests_per_minute=20)
async def fetch_and_parse(self, url: str, ctx: Context) -> str:
"""Fetch and parse content from a webpage"""
try:
await self.rate_limiter.acquire()
await ctx.info(f"Fetching content from: {url}")
async with httpx.AsyncClient() as client:
response = await client.get(
url,
headers={
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
},
follow_redirects=True,
timeout=30.0,
)
response.raise_for_status()
# Parse the HTML
soup = BeautifulSoup(response.text, "html.parser")
# Remove script and style elements
for element in soup(["script", "style", "nav", "header", "footer"]):
element.decompose()
# Get the text content
text = soup.get_text()
# Clean up the text
lines = (line.strip() for line in text.splitlines())
chunks = (phrase.strip() for line in lines for phrase in line.split(" "))
text = " ".join(chunk for chunk in chunks if chunk)
# Remove extra whitespace
text = re.sub(r"\s+", " ", text).strip()
# Truncate if too long
if len(text) > 8000:
text = text[:8000] + "... [content truncated]"
await ctx.info(
f"Successfully fetched and parsed content ({len(text)} characters)"
)
return text
except httpx.TimeoutException:
await ctx.error(f"Request timed out for URL: {url}")
return "Error: The request timed out while trying to fetch the webpage."
except httpx.HTTPError as e:
await ctx.error(f"HTTP error occurred while fetching {url}: {str(e)}")
return f"Error: Could not access the webpage ({str(e)})"
except Exception as e:
await ctx.error(f"Error fetching content from {url}: {str(e)}")
return f"Error: An unexpected error occurred while fetching the webpage ({str(e)})"
# Initialize FastMCP server
mcp = FastMCP("ddg-search")
searcher = DuckDuckGoSearcher()
fetcher = WebContentFetcher()
@mcp.tool()
async def search(query: str, ctx: Context, max_results: int = 10) -> str:
"""
Search DuckDuckGo and return formatted results.
Args:
query: The search query string
max_results: Maximum number of results to return (default: 10)
ctx: MCP context for logging
"""
try:
results = await searcher.search(query, ctx, max_results)
return searcher.format_results_for_llm(results)
except Exception as e:
traceback.print_exc(file=sys.stderr)
return f"An error occurred while searching: {str(e)}"
@mcp.tool()
async def fetch_content(url: str, ctx: Context) -> str:
"""
Fetch and parse content from a webpage URL.
Args:
url: The webpage URL to fetch content from
ctx: MCP context for logging
"""
return await fetcher.fetch_and_parse(url, ctx)
def main():
mcp.run()
if __name__ == "__main__":
main()
```