MCP Server for searching via DuckDuckGo (Node.js version)
npm install duckduckgo-websearchip
bash
Install globally via npm
npm install -g duckduckgo-websearch
Or using pnpm
pnpm add -g duckduckgo-websearch
Or using yarn
yarn global add duckduckgo-websearch
`
After global installation, you can use the following commands:
- npx duckduckgo-websearch
- npx ddg-websearch
- duckduckgo-websearch
- ddg-websearch (short alias)
$3
`bash
Clone and install locally
git clone https://github.com/HeiSir2014/duckduckgo-mcp-server
cd duckduckgo-mcp-server
npm install
npm run build
`
Usage
$3
After global installation, you can run the server directly:
`bash
Start the server
npx duckduckgo-websearch
Or using the short alias
npx ddg-websearch
or
duckduckgo-websearch
Or using the short alias
ddg-websearch
`
$3
1. Download Claude Desktop
2. Create or edit your Claude Desktop configuration:
- On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- On Windows: %APPDATA%\Claude\claude_desktop_config.json
#### For Global Installation:
`json
{
"mcpServers": {
"ddg-search": {
"command": "npx duckduckgo-websearch"
}
}
}
`
#### For Local Installation:
`json
{
"mcpServers": {
"ddg-search": {
"command": "node",
"args": ["path/to/duckduckgo-mcp-server/build/index.js"]
}
}
}
`
3. Restart Claude Desktop
$3
For local development:
`bash
Install dependencies
npm install
Build the project
npm run build
Run in development mode
npm run dev
Start the built server
npm start
Run tests
npm test
`
Available Tools
$3
`typescript
async function search(query: string, max_results?: number): Promise
`
Performs a web search on DuckDuckGo and returns formatted results.
Parameters:
- query: Search query string
- max_results: Maximum number of results to return (default: 10)
Returns:
Formatted string containing search results with titles, URLs, and snippets.
$3
`typescript
async function fetch_content(url: string, max_length?: number): Promise
`
Fetches and parses content from a webpage.
Parameters:
- url: The webpage URL to fetch content from
- max_length: Maximum content length to return (default: 8000)
Returns:
Cleaned and formatted text content from the webpage.
Features in Detail
$3
- Search: Limited to 30 requests per minute
- Content Fetching: Limited to 20 requests per minute
- Automatic queue management and wait times
$3
- Removes ads and irrelevant content
- Cleans up DuckDuckGo redirect URLs
- Formats results for optimal LLM consumption
- Truncates long content appropriately
$3
- Comprehensive error catching and reporting
- Graceful degradation on rate limits or timeouts
Technical Details
$3
- @modelcontextprotocol/sdk: MCP SDK for Node.js
- cheerio: Server-side jQuery implementation for HTML parsing
- Node.js 内置 fetch API：用于 HTTP 请求（无需额外依赖）
$3
The server is built using the MCP SDK and consists of several key components:
- DuckDuckGoSearcher: Handles search requests with rate limiting
- WebContentFetcher: Fetches and parses webpage content
- RateLimiter: Manages request rate limiting
- Main Server: Integrates everything and handles MCP protocol
Publishing (For Maintainers)
$3
`bash
Update version
npm run version:patch # 0.1.1 -> 0.1.2
npm run version:minor # 0.1.1 -> 0.2.0
npm run version:major # 0.1.1 -> 1.0.0
`
$3
`bash
Check publish readiness
npm run publish:check
Publish (after version update)
npm publish
`
$3
- [ ] All tests pass (npm test)
- [ ] Build succeeds (npm run build)
- [ ] Version updated (npm version [patch|minor|major]`)