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.
[](https://opensource.org/licenses/MIT)
[](https://github.com/gianlucamazza/mcp-duckduckgo)
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:
From Source
- Clone this repository: ```bash git clone https://github.com/gianlucamazza/mcp-duckduckgo.git cd mcp-duckduckgo ```
- Install the package in development mode: ```bash pip install -e . ``` Or use the provided script: ```bash ./scripts/install_dev.sh ``` Or use Make: ```bash make install ```
Usage
Starting the Server Manually
To start the MCP server:
Or with custom parameters:
Or use the provided script for development:
Or use Make:
Using with Claude Code
- Install the package from source as described above.
- Configure Claude Code to use the plugin: ```bash claude mcp add duckduckgo-search -- mcp-duckduckgo ```
- For global configuration (available in all projects): ```bash claude mcp add duckduckgo-search --scope global -- mcp-duckduckgo ```
- Start Claude Code: ```bash 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:
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:
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:
Resource: `docs://search`
Provides comprehensive documentation about the search functionality.
Example usage in Claude Code:
Prompt: `search_assistant`
Helps formulate effective search queries.
Example usage in Claude Code:
Resource: `search://{query}`
Retrieves formatted search results for a specific query.
Example usage in Claude Code:
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:
Filtering Results
To filter results by specific site:
To filter results by time period:
Exploring Result Details
To get more information about a specific search result:
Finding Related Searches
To discover related search queries:
These navigation features can be combined with Claude's natural language capabilities to create a powerful search and exploration experience. For example:
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:
To control spidering behavior:
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:
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:
Running Tests
You can run all tests with:
To run tests with coverage reporting:
To run a specific test file:
To run tests with verbose output:
Or use the provided script:
Or use Make:
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](tests/README.md) file.
Code Formatting and Linting
Or use the provided script:
Or use Make:
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: ```bash pip install build twine ```
- Build and publish: ```bash python -m build twine upload dist/* ```
Or use the provided script if available:
Or use Make:
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
[MIT](LICENSE)
Repository
https://github.com/gianlucamazza/mcp-duckduckgo