MCP DuckDuckGo Search Plugin

A DuckDuckGo search plugin for Model Context Protocol (MCP), compatible with Claude Code. Provides web search functionality with advanced navigation and content exploration features.

Description

This project implements a Model Context Protocol (MCP) server that provides web search functionality using DuckDuckGo. The plugin is designed to work seamlessly with Claude Code or any other client that supports MCP, offering not just basic search capabilities but also advanced navigation and result exploration features.

Features

Web Search Tool: Perform web searches using DuckDuckGo
Detailed Results: Get detailed information about specific search results
Related Searches: Discover related search queries based on your original search
Pagination Support: Navigate through multiple pages of search results
Domain Extraction: View domain information for each search result
Advanced Filtering: Filter results by site and time period
Enhanced Content Extraction: Extract rich content from webpages including metadata, structure, and snippets
Basic Web Spidering: Follow links from search results to explore related content (configurable depth)
Metadata Extraction: Extract titles, authors, keywords, publication dates, and more
Social Media Detection: Identify and extract social media links from webpages
Content Structure Analysis: Extract headings and sections to understand webpage structure
Search Documentation: Access comprehensive documentation about the search functionality
Search Assistant: Get help formulating effective search queries
Parameterized Resource: Retrieve formatted search results for specific queries

Requirements

Python 3.9 or higher
pip (Python package manager)
Python packages listed in pyproject.toml

Installation

From PyPI

Note: This package is not yet published to PyPI. Please install from source below.

In the future, once published, you'll be able to install with:

pip install mcp-duckduckgo

From Source

Clone this repository:

git clone https://github.com/gianlucamazza/mcp-duckduckgo.git
cd mcp-duckduckgo

Install the package in development mode:
```
pip install -e .
```
Or use the provided script:
```
./scripts/install_dev.sh
```
Or use Make:
```
make install
```

Usage

Starting the Server Manually

To start the MCP server:

mcp-duckduckgo

Or with custom parameters:

mcp-duckduckgo --host 127.0.0.1 --port 8000

Or use the provided script for development:

./scripts/run.sh

Or use Make:

make run

Using with Claude Code

Install the package from source as described above.

Configure Claude Code to use the plugin:

claude mcp add duckduckgo-search -- mcp-duckduckgo

For global configuration (available in all projects):

claude mcp add duckduckgo-search --scope global -- mcp-duckduckgo

Start Claude Code:
```
claude
```
Now you can use the DuckDuckGo search functionality within Claude Code.

Available Endpoints

The plugin provides the following endpoints:

Tool: `duckduckgo_web_search`

Performs a web search using DuckDuckGo with the following parameters:

query (required): The search query (max 400 characters, 50 words)
count (optional, default: 10): Number of results per page (1-20)
page (optional, default: 1): Page number for pagination
site (optional): Limit results to a specific site (e.g., 'example.com')
time_period (optional): Filter results by time period ('day', 'week', 'month', 'year')

Example usage in Claude Code:

Search for "artificial intelligence latest developments"

Tool: `duckduckgo_get_details`

Retrieves detailed information about a specific search result:

url (required): URL of the result to get details for

Example usage in Claude Code:

Get details for "https://example.com/article"

Tool: `duckduckgo_related_searches`

Suggests related search queries based on the original query:

query (required): Original search query (max 400 characters)
count (optional, default: 5): Number of related searches to return (1-10)

Example usage in Claude Code:

Find related searches for "renewable energy"

Resource: `docs://search`

Provides comprehensive documentation about the search functionality.

Example usage in Claude Code:

Show me the documentation for the DuckDuckGo search

Prompt: `search_assistant`

Helps formulate effective search queries.

Example usage in Claude Code:

Help me formulate a search query about climate change solutions

Resource: `search://{query}`

Retrieves formatted search results for a specific query.

Example usage in Claude Code:

Get search results for "quantum computing breakthroughs"

Using the Navigation Features

The plugin provides several features to help navigate and explore search results:

Pagination

To navigate through multiple pages of search results:

Search for "climate change solutions" with 5 results per page, page 2

Filtering Results

To filter results by specific site:

Search for "machine learning tutorials" on "tensorflow.org"

To filter results by time period:

Search for "latest news" from the past week

Exploring Result Details

To get more information about a specific search result:

Get details for "https://example.com/article-found-in-search"

Finding Related Searches

To discover related search queries:

Find related searches for "electric vehicles"

These navigation features can be combined with Claude's natural language capabilities to create a powerful search and exploration experience. For example:

Search for "python machine learning libraries", then get details on the top result, and finally show me related search terms

Implementation Notes

This implementation uses DuckDuckGo's public web interface and parses the HTML response to extract results. This approach is used for demonstration purposes, as DuckDuckGo does not offer an official search API. In a production environment, it's recommended to use a search service with an official API.

Enhanced Content Extraction

The DuckDuckGo plugin includes advanced content extraction capabilities that go beyond simple search results:

Content Extraction Features

Full Webpage Analysis: Extract and parse HTML content from search result URLs
Intelligent Content Targeting: Identify and extract main content areas from different types of websites
Rich Metadata Extraction: Extract titles, descriptions, authors, keywords, and publication dates
Image Detection: Identify and extract main images and media from webpages
Social Media Integration: Detect and extract links to social media profiles
Content Structure Analysis: Extract headings and sections to understand webpage organization
Official Source Detection: Identify whether a source is official based on domain and content signals

Web Spidering Capabilities

The plugin includes basic web spidering functionality:

Configurable Depth: Follow links from 0 to 3 levels deep from the original URL
Link Limitation: Control the maximum number of links to follow per page (1-5)
Domain Restriction: Option to only follow links within the same domain
Related Content Discovery: Find and analyze content related to the original search

Using Enhanced Content Extraction

To use the enhanced content extraction features:

Get details for "https://example.com/article" with spider depth 1

To control spidering behavior:

Get details for "https://example.com/article" with spider depth 2, max links 3, same domain only

Development

The project includes several utility scripts in the scripts directory to help with development:

install_dev.sh: Sets up the development environment
run.sh: Runs the MCP server with development settings
test.sh: Runs tests with coverage reporting
lint.sh: Runs linting and code formatting
publish.sh: Builds and publishes the package to PyPI

For convenience, a Makefile is also provided with the following targets:

make install  # Install the package in development mode
make test     # Run tests with coverage
make lint     # Run linting and code formatting
make run      # Run the MCP server
make publish  # Build and publish the package to PyPI
make clean    # Clean build artifacts
make all      # Run install, lint, and test (default)
make help     # Show help message

Testing

The project includes a comprehensive test suite covering all major functionality. Tests are located in the tests/ directory.

Installing Test Dependencies

Before running the tests, install the test dependencies:

pip install -e ".[test]"

Running Tests

You can run all tests with:

pytest

To run tests with coverage reporting:

pytest --cov=mcp_duckduckgo

To run a specific test file:

pytest tests/test_models.py

To run tests with verbose output:

pytest -v

Or use the provided script:

./scripts/test.sh

Or use Make:

make test

Test Structure

The test suite is organized as follows:

conftest.py - Shared fixtures and configurations for tests
test_models.py - Tests for data models
test_search.py - Tests for search functionality
test_tools.py - Tests for MCP tools
test_resources.py - Tests for MCP resources
test_integration.py - End-to-end integration tests
test_server.py - Server lifecycle tests

For more details about testing, see the tests/README.md file.

Code Formatting and Linting

black mcp_duckduckgo
isort mcp_duckduckgo
mypy mcp_duckduckgo

Or use the provided script:

./scripts/lint.sh

Or use Make:

make lint

Publishing to PyPI

If you want to publish the package to PyPI:

Update the version in pyproject.toml
Ensure you have the necessary credentials and tools:
```
pip install build twine
```
Build and publish:
```
python -m build
twine upload dist/*
```

Or use the provided script if available:

./scripts/publish.sh

Or use Make:

make publish

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Repository

https://github.com/gianlucamazza/mcp-duckduckgo