DuckDuckGo MCP Search Server

0.1.2 · active · verified Wed Apr 22

This package provides a Model Context Protocol (MCP) server implemented in TypeScript, enabling AI agents and applications to perform web searches using DuckDuckGo. Currently at version 0.1.2, it is in active development, with minor releases likely to address features and fixes. Its core functionality revolves around exposing a `duckduckgo_search` tool, which allows clients to query the web with parameters like `query`, `count`, and `safeSearch`. Key differentiators include its adherence to the MCP standard, robust rate limiting (1 req/sec, 15000 req/month), and integrated error handling, making it a reliable bridge for AI applications needing up-to-date search capabilities without direct API integration. It requires Node.js >= 18 and pnpm >= 8.0.0 to run, and is designed to be invoked as a command-line process rather than imported as a traditional JavaScript library.

Common errors

```
command not found: npx
```
cause Node.js or npm is not installed, or their executable paths are not correctly configured in the system's PATH environment variable.

fix Install Node.js (which includes npm and npx) from nodejs.org, ensuring it's version >=18. Verify installation with `node -v` and `npm -v`.
```
Error: Rate limit exceeded
```
cause The client has sent requests faster than 1 per second or exceeded the 15,000 monthly request limit imposed by the MCP server.

fix Implement a delay or a queuing mechanism on the client-side to ensure requests adhere to the server's rate limits (1 req/sec, 15,000 req/month).
```
Error: EACCES: permission denied, open '/path/to/claude_desktop_config.json'
```
cause The user running the client application (e.g., Claude Desktop) or the MCP server does not have sufficient write permissions to modify the configuration file.

fix Adjust file permissions for the affected configuration file (e.g., `claude_desktop_config.json`) to allow write access for the current user. On Unix-like systems, `chmod 600 /path/to/file.json` might be required.

Warnings

gotcha The DuckDuckGo MCP Server enforces strict rate limits: a maximum of 1 request per second and 15,000 requests per month. Exceeding these limits will result in error responses from the server.
Fix: Implement client-side rate limiting or retry mechanisms with exponential backoff to ensure requests adhere to the server's specified limits.
gotcha This package is an early-stage release (version 0.1.2), indicating potential for API changes, instability, and unannounced breaking changes in minor or patch versions. It may not be suitable for production environments requiring high stability.
Fix: Monitor the GitHub repository for updates and breaking changes. Pin exact versions in production deployments and thoroughly test before upgrading.
gotcha The server communicates via the Model Context Protocol (MCP) over standard I/O (stdio). This pattern can make traditional debugging challenging without specialized tools like the MCP Inspector.
Fix: Utilize the provided `pnpm run inspector` command, which launches the MCP Inspector, to effectively debug stdio communication between your client and the server. Ensure your client correctly formats MCP messages.

Install

npm install duckduckgo-mcp-server npm
yarn add duckduckgo-mcp-server yarn
pnpm add duckduckgo-mcp-server pnpm

Imports

duckduckgo_search
wrong:
```
import { duckduckgo_search } from 'duckduckgo-mcp-server';
```
correct:
```
/* Client sends JSON to MCP server via stdio: */
{
  "tool": "duckduckgo_search",
  "args": {
    "query": "latest AI news",
    "count": 5,
    "safeSearch": "moderate"
  }
}
```
This package is an MCP *server*. 'duckduckgo_search' refers to the named tool it exposes via the Model Context Protocol, not a direct JavaScript export. Clients (e.g., AI agents) interact with it by sending structured JSON requests over standard I/O (stdio).
ServerCLI
wrong:
```
import { ServerCLI } from 'duckduckgo-mcp-server';
```
correct:
```
npx duckduckgo-mcp-server
```
To run the server directly from npm without global installation, use `npx`. This is common for on-demand use or in containerized environments. It initiates the MCP server process, listening for stdio commands.
LocalServerExecution
wrong:
```
const LocalServerExecution = require('duckduckgo-mcp-server/server');
```
correct:
```
node /path/to/your/cloned/repo/build/index.js
```
For persistent local deployment or development, the server can be built and run directly via Node.js. Replace `/path/to/your/cloned/repo/build/index.js` with your actual build output path after running `pnpm run build`.

Quickstart

Demonstrates how to quickly run the DuckDuckGo MCP server using npx and integrate its capabilities into a client application like Claude Desktop. This setup allows the client to utilize the 'duckduckgo_search' tool via the Model Context Protocol.

# 1. Ensure Node.js (>=18) and pnpm (>=8) are installed.
# 2. To run the server for ad-hoc use (e.g., via a client like Claude Desktop):
npx duckduckgo-mcp-server

# 3. For integration with Claude Desktop (MacOS example):
# Add the following JSON configuration to ~/Library/Application Support/Claude/claude_desktop_config.json
# For Windows: %APPDATA%/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "duckduckgo-search": {
        "command": "npx",
        "args": ["-y", "duckduckgo-mcp-server"]
    }
  }
}

# After configuring, restart Claude Desktop. It can then utilize the 'duckduckgo_search' tool for web searches.

view raw JSON →