Registry / llm-agents / duckduckgo-mcp-server

duckduckgo-mcp-server

library0.4.0jsnpmunverified

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.

llm-agents http-networking

npm install duckduckgo-mcp-server

github ↗package ↗

INSTALL

IMPORT

SIG · DUCKDUCKGO-MCP-SER

duckduckgo-mcp-server

llm-agentsjavascriptv0.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

duckduckgo_search

✓ /* Client sends JSON to MCP server via stdio: */ { "tool": "duckduckgo_search", "args": { "query": "latest AI news", "count": 5, "safeSearch": "moderate" } }

✗ import { duckduckgo_search } from 'duckduckgo-mcp-server';

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

✓ npx duckduckgo-mcp-server

✗ import { ServerCLI } from '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

✓ node /path/to/your/cloned/repo/build/index.js

✗ const LocalServerExecution = require('duckduckgo-mcp-server/server');

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`.

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.

duckduckgo-mcp-server --version

Debug

Known issues

gotchaThe 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.

affects: >=0.1.0

gotchaThis 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.

affects: >=0.1.0

gotchaThe 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.

affects: >=0.1.0

Errors

Common errors & fixes

command not found: npx

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

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'

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.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

noderequiredRuntime environment for the TypeScript server.

pnpmrequiredPackage manager used for installation and script execution.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zhsama/duckduckgo-mcp-server ↗

packagehttps://www.npmjs.com/package/duckduckgo-mcp-server ↗