Mirror notice: This repository is a one-way published export of a privately hosted project. History is squashed into sync snapshots, and pull requests cannot be merged here directly — open an issue instead. Changes land in the private source and are re-exported.

A high-performance Model Context Protocol (MCP) sub-server providing secure web search and media discovery via DuckDuckGo.

mcp-server-duckduckgo update            # confirm, then install the latest release
mcp-server-duckduckgo update --check    # report only; exit 10 if an update is available
mcp-server-duckduckgo update --version v1.1.0   # install that exact release

--check reports only (exit 0 up to date, 10 actionable, 1 error) and contradicts --yes/--force. --yes/-y approves without prompting; a non-interactive apply without it fails rather than hanging. --force replaces a locally built binary or reinstalls the selected version, and never bypasses version, asset, size, integrity or target checks. --version vX.Y.Z installs an exact release; a lower tag is reported as an explicit rollback.

update creates no cache directory or config.yaml and starts no datastore, browser, search engine, tool registry, transport or MCP server. Its output goes to stderr so the JSON-RPC stdout stays protocol-clean. Set GH_TOKEN or GITHUB_TOKEN to raise GitHub API rate limits; the token is sent only to the GitHub API origin.

Supported platforms are linux/amd64, darwin/arm64 and windows/amd64. A binary you built yourself is a local build and update refuses to replace it without --force. If you installed through a package manager, update through that manager instead — self-update does not take ownership of package-manager installs.

Releases are immutable vMAJOR.MINOR.PATCH tags publishing the exact mcp-server-duckduckgo-<goos>-<goarch>[.exe] assets and one SHA256SUMS. A rebuilt fix gets a new patch tag rather than replacing a published asset (mcplib MADR 0005).

AI models suffer from training cutoff limits and lack real-time visibility into the public web, documentation updates, and breaking news. Commercial search APIs often require complex api-key signups, implement severe rate limits, and track queries. mcp-server-duckduckgo exists to give AI agents a zero-configuration, privacy-preserving gateway to retrieve live web context, documentation, and media assets using DuckDuckGo.

The DuckDuckGo sub-server enables search and web scraping workflows:

• Web & News Search: Searches active websites and current news feeds.
• Media Discovery: Finds related images and videos.
• Direct Web Scraping: Fetches webpage content and dynamically converts it into clean, readable Markdown for prompt injection.
• Search Suggestions: Retrieves search query autocompletion suggestions.

• HTML Parsing & Extraction: Queries DuckDuckGo HTML endpoints directly, parsing results concurrently with Go's net/http client.
• Jit Web Reader: The read_url tool fetches remote HTML pages, strips script/style tags, and structures the content as Markdown.
• Telemetry Logging: Writes process lifecycle logs to a high-fidelity ring buffer and routes standard error streams safely to the orchestrator.

Download the mcp-server-duckduckgo binary for your platform and place it in a directory on your system PATH.

# Move the binary to your local bin directory
mv mcp-server-duckduckgo ~/.local/bin/mcp-server-duckduckgo
chmod +x ~/.local/bin/mcp-server-duckduckgo

# Move the binary to your local bin directory
mv mcp-server-duckduckgo /usr/local/bin/mcp-server-duckduckgo
chmod +x /usr/local/bin/mcp-server-duckduckgo

# Create a directory for the binary if it doesn't exist
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\Programs\duckduckgo"

# Move the binary
Move-Item mcp-server-duckduckgo.exe "$env:LOCALAPPDATA\Programs\duckduckgo\mcp-server-duckduckgo.exe"

# Add to your PATH (current user, persistent)
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$currentPath;$env:LOCALAPPDATA\Programs\duckduckgo", "User")

mcp-server-duckduckgo is a stateless sub-server. It does not require local configuration files, API tokens, or initialization steps like init or configure.

⚠️ IMPORTANT ORCHESTRATOR MESSAGING

While the standalone IDE configurations below are provided for testing and debugging, mcp-server-duckduckgo is designed to be run as a downstream node behind the magictools orchestrator in production environments.

When running in production, you should only configure magictools in your IDE, which will automatically proxy requests to duckduckgo as needed.

If you are testing the server standalone, configure your IDE to launch the binary directly (no serve argument is needed):

Linux / macOS:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "/home/youruser/.local/bin/mcp-server-duckduckgo",
      "env": {
        "HOME": "/home/youruser"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "C:\\Users\\YourUser\\AppData\\Local\\Programs\\duckduckgo\\mcp-server-duckduckgo.exe",
      "env": {
        "USERPROFILE": "C:\\Users\\YourUser"
      }
    }
  }
}

Linux:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "/home/youruser/.local/bin/mcp-server-duckduckgo",
      "env": {
        "HOME": "/home/youruser"
      }
    }
  }
}

macOS:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "/usr/local/bin/mcp-server-duckduckgo",
      "env": {
        "HOME": "/Users/youruser"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "C:\\Users\\YourUser\\AppData\\Local\\Programs\\duckduckgo\\mcp-server-duckduckgo.exe",
      "env": {
        "USERPROFILE": "C:\\Users\\YourUser"
      }
    }
  }
}

Linux:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "/home/youruser/.local/bin/mcp-server-duckduckgo",
      "env": {
        "HOME": "/home/youruser"
      }
    }
  }
}

macOS:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "/usr/local/bin/mcp-server-duckduckgo",
      "env": {
        "HOME": "/Users/youruser"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "C:\\Users\\YourUser\\AppData\\Local\\Programs\\duckduckgo\\mcp-server-duckduckgo.exe",
      "env": {
        "USERPROFILE": "C:\\Users\\YourUser"
      }
    }
  }
}

macOS:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "/usr/local/bin/mcp-server-duckduckgo",
      "env": {
        "HOME": "/Users/youruser"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "C:\\Users\\YourUser\\AppData\\Local\\Programs\\duckduckgo\\mcp-server-duckduckgo.exe",
      "env": {
        "USERPROFILE": "C:\\Users\\YourUser"
      }
    }
  }
}

Claude Code uses a CLI command to register MCP servers.

Linux:

claude mcp add duckduckgo -s user -- /home/youruser/.local/bin/mcp-server-duckduckgo

macOS:

claude mcp add duckduckgo -s user -- /usr/local/bin/mcp-server-duckduckgo

Windows (PowerShell):

claude mcp add duckduckgo -s user -- "C:\Users\YourUser\AppData\Local\Programs\duckduckgo\mcp-server-duckduckgo.exe"

Linux:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "/home/youruser/.local/bin/mcp-server-duckduckgo",
      "env": {
        "HOME": "/home/youruser"
      }
    }
  }
}

macOS:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "/usr/local/bin/mcp-server-duckduckgo",
      "env": {
        "HOME": "/Users/youruser"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "C:\\Users\\YourUser\\AppData\\Local\\Programs\\duckduckgo\\mcp-server-duckduckgo.exe",
      "env": {
        "USERPROFILE": "C:\\Users\\YourUser"
      }
    }
  }
}

JetBrains IDEs configure MCP servers via the AI Assistant settings or a local configuration file.

Linux:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "/home/youruser/.local/bin/mcp-server-duckduckgo",
      "env": {
        "HOME": "/home/youruser"
      }
    }
  }
}

macOS:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "/usr/local/bin/mcp-server-duckduckgo",
      "env": {
        "HOME": "/Users/youruser"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "duckduckgo": {
      "command": "C:\\Users\\YourUser\\AppData\\Local\\Programs\\duckduckgo\\mcp-server-duckduckgo.exe",
      "env": {
        "USERPROFILE": "C:\\Users\\YourUser"
      }
    }
  }
}

mcp-server-duckduckgo is stateless and does not require local configuration files. You can configure execution behavior using the following environment variables:

Once the server is running, the following tools are exposed:

Built with ❤️. Part of the MagicTools Intelligence Suite.