ddg_mcp_server

This MCP server exposes a web-based DuckDuckGo search interface powered by a Python backend and Gradio. It uses DuckDuckGo's search API to fetch real-time results, formats them with Markdown, and offers AI-powered content summarization via an OpenAI-compatible API. The interface is served through a Gradio web app, making it easy to search, view full results, and read concise summaries generated by the summarization feature. You can configure the number of results and ensure the OpenAI-like service is reachable by supplying credentials in the environment.

To use the server, start it with the provided command (for example, running main.py with a Python environment or via Docker). Open your browser to the app URL (typically http://localhost:7860) to perform searches. The API credentials for summarization are provided through environment variables (OPENAI_API_URL and ACCESS_TOKEN). If you have a compatible API endpoint, you can customize the model and endpoint URL via the config file to tailor the summarization behavior. See the SUMMARIZATION.md document referenced in the repo for deeper details on how summaries are generated and configurable models.

Prerequisites:

• Python 3.10+ or Docker installation
• Git (optional, for cloning)
• Access to a DuckDuckGo API (via the included integration)
• Optional: OpenAI-compatible API endpoint and credentials for summarization

Option 1: Run with Docker

1. Ensure Docker is installed and running.
2. Build the image (from the project folder):

docker build -t ddg-mcp-server .

3. Run the container exposing port 7860:

docker run -p 7860:7860 ddg-mcp-server

4. Open http://localhost:7860 to access the app.

Option 2: Run locally with Python

1. Clone the repository and navigate to the project folder:

git clone <repository-url>
cd ddg_mcp_server

2. Create and activate a virtual environment (optional but recommended):

python -m venv venv
source venv/bin/activate  # on macOS/Linux
venv\Scripts\activate  # on Windows

3. Install dependencies (assumes a requirements.txt is present):

pip install -r requirements.txt

4. Copy the example env file and set credentials:

cp .env.example .env

Edit .env to include OPENAI_API_URL and ACCESS_TOKEN as needed. Then run the app:

python main.py

5. The app will be available at http://localhost:7860 (adjust if you change the port).

Prerequisites recap: ensure you have Python 3.10+, pip, and network access to DuckDuckGo and the optional OpenAI-compatible API for summarization.

Tips and common issues:

• If you rely on the AI summarization feature, ensure OPENAI_API_URL and ACCESS_TOKEN are correctly set in the environment or in .env. The default API URL can be the official OpenAI endpoint unless overridden.
• When running in Docker, pass environment variables through -e OPENAI_API_URL=... -e ACCESS_TOKEN=... to enable summarization.
• The server listens on port 7860 by default; adjust port mappings if you need to expose it elsewhere.
• If you encounter connectivity issues, verify that the container or local process has network access to DuckDuckGo and the OpenAI API and that API keys are valid.
• The configuration for summarization model can be changed in the config.py file; refer to SUMMARIZATION.md for details on supported models and settings.