Content
# MCP Search Server
[English](./README.en.md) |
<div align="center">
Multi-engine aggregated search local MCP server — **8 engines in parallel** + **deduplication and sorting** + **web body extraction** + **in-depth research**.
[](LICENSE)
[](package.json)
Compatible with **Cursor** · **Claude Desktop** · **Continue.dev** · **Windsurf** · **Trae**
**Privacy and Security** · **Zero API Fees** · **Fully Open Source** · **Deployable on Private Network**
</div>
---
## Table of Contents
- [Features](#features)
- [Search Engines](#search-engines)
- [Quick Start](#quick-start)
- [Client Configuration](#client-configuration)
- [Environment Variables](#environment-variables)
- [MCP Tools](#mcp-tools)
- [Project Structure](#project-structure)
- [Usage Examples](#usage-examples)
---
## Features
- **Multi-engine Parallel Search** — Simultaneously call 8 search engines; `Promise.allSettled` ensures that a single engine failure does not affect the overall process.
- **In-depth Research** — `research` one-click search → crawl → comprehensive conclusion.
- **Composite Tool** — `search_and_fetch` searches and crawls the body simultaneously.
- **Search Session** — Results are persisted, and `refine` allows for secondary filtering (engine/keyword/domain/pagination).
- **Search Scenarios** — `profile` parameter: general / tech / chinese / code / fast / deep.
- **Result Aggregation** — Multi-engine deduplication (URL + title similarity), relevance scoring and sorting, and balanced engine output.
- **Query Expansion** — Automatically expand queries with synonyms when results are insufficient to improve recall.
- **Useless Information Filtering** — Remove advertising words, navigation words, tracking parameters/domains, short summaries, and error pages.
- **Web Crawling** — Use Mozilla Readability to extract the body, automatically delete duplicate paragraphs, copyright declarations, and footer recommendations.
- **Disk Cache** — 5-minute TTL, repeated queries respond in seconds.
- **Circuit Breaker Protection** — Automatically cool down for 30 seconds after engine consecutive failures, and fully reset after success.
- **MCP Protocol** — Standard stdio transmission, Cursor/Claude Desktop plug-and-play.
- **Privacy and Security** — Run locally, and search records do not pass through any third-party server.
- **Zero API Fees** — Directly call free search engines, no paid API required.
- **Anti-scraping Strategy** — UA rotation, request header randomization, pagination random delay, and general verification detection.
- **Headless Browser** — Set `HEADLESS_BROWSER=true` to enable Puppeteer, Zhihu direct connection search, bypass 403 restrictions.
- **Configurable** — Freely combine engines through environment variables.
---
## Search Engines
| Engine | Type | Description |
|------|------|------|
| `bing` | General | Microsoft Bing, good for Chinese search results |
| `baidu` | General | Baidu Search |
| `360` | General | 360 Search (so.com), available in China |
| `sogou` | General | Sogou Search (strict anti-scraping) |
| `duckduckgo` | General | DuckDuckGo (may be blocked by domestic networks) |
| `brave` | General | Brave Search (may be blocked by domestic networks) |
| `github` | Code | GitHub repository search |
| `zhihu` | Content | Zhihu (searched through Bing `site:`) |
Default enabled: `bing` `baidu` `360` `github` `zhihu`
> Domestic network suggestions: sogou / duckduckgo / brave may fail, can be disabled using `SEARCH_DISABLED_ENGINES`.
---
## Quick Start
```bash
git clone https://github.com/ZhenMoon/mcp-search-server.git
cd mcp-search-server
npm install
npm run build
```
---
## Client Configuration
Add the following entry to the MCP client configuration (replace `<path>` with your actual path):
```json
{
"mcpServers": {
"mcp-search": {
"command": "node",
"args": ["<path>/mcp-search-server/build/index.js"]
}
}
}
```
**Configuration File Location:**
| Client | Configuration File Path |
|--------|-------------|
| Cursor | `~/.cursor/mcp.json` |
| Claude Desktop | `~/.claude/settings.json` |
| Continue.dev | `~/.continue/config.json` |
| Windsurf / Trae | Add the same command/args in MCP configuration |
---
## Environment Variables
| Variable | Description | Example |
|------|------|------|
| `SEARCH_ENGINES` | Enable specified engines (comma-separated) | `bing,baidu,360` |
| `SEARCH_DISABLED_ENGINES` | Disable specified engines | `duckduckgo,brave,sogou` |
| `HEADLESS_BROWSER` | Enable headless browser (requires Chrome/Edge) | `true` |
| `BRAVE_API_KEY` | Brave Search API key (free 1000/month) | Apply at https://brave.com/search/api/ |
Enabling the headless browser allows the Zhihu engine to directly connect to Zhihu search through Puppeteer (instead of relying on Bing `site:`), resulting in higher search quality.
Setting `BRAVE_API_KEY` allows the Brave engine to use the official API, and domestic networks can stably return international search results.
Domestic network suggestions:
```bash
SEARCH_DISABLED_ENGINES=duckduckgo,brave,sogou node build/index.js
```
---
## MCP Tools
### `search` — Multi-engine Aggregated Search
| Parameter | Type | Default | Description |
|------|------|--------|------|
| `query` | `string` | **Required** | Search keyword |
| `maxResults` | `number` | `10` | Maximum number of results returned (1–50) |
| `engines` | `string[]` | Default 5 engines | Search engine list |
| `timeout` | `number` | `15000` | Search timeout (milliseconds) |
| `profile` | `string` | — | Search scenario: `general`/`tech`/`chinese`/`code`/`fast`/`deep` |
Returns results containing `【Session ID】`, which can be used for `refine` tool secondary filtering.
### `refine` — Refine Search Results
| Parameter | Type | Default | Description |
|------|------|--------|------|
| `sessionId` | `string` | **Required** | `search` returned session ID |
| `engine` | `string` | — | Filter by engine, comma-separated |
| `keyword` | `string` | — | Keyword filtering |
| `domain` | `string` | — | Domain filtering |
| `offset` | `number` | `0` | Offset |
| `limit` | `number` | `10` | Number of results returned |
### `search_profiles` — List Available Search Scenarios
No parameters.
### `search_engines` — List Available Search Engines
No parameters.
### `fetch` — Crawl Web Page Body
| Parameter | Type | Default | Description |
|------|------|--------|------|
| `url` | `string` | **Required** | Web page URL |
| `timeout` | `number` | `15000` | Crawl timeout (milliseconds) |
| `maxLength` | `number` | `8000` | Maximum length of returned content |
### `search_and_fetch` — Search + Crawl Body
| Parameter | Type | Default | Description |
|------|------|--------|------|
| `query` | `string` | **Required** | Search keyword |
| `maxResults` | `number` | `5` | Number of search results |
| `fetchCount` | `number` | `3` | Crawl top N bodies |
| `engines` | `string[]` | Default 5 engines | Search engine list |
| `timeout` | `number` | `15000` | Timeout (milliseconds) |
| `profile` | `string` | — | Search scenario |
### `research` — In-depth Research (Search → Crawl → Comprehensive Report)
| Parameter | Type | Default | Description |
|------|------|--------|------|
| `query` | `string` | **Required** | Research topic |
| `maxResults` | `number` | `8` | Number of search results |
| `fetchCount` | `number` | `3` | Read top N in-depth |
| `engines` | `string[]` | Default 5 engines | Search engine list |
| `timeout` | `number` | `20000` | Timeout (milliseconds) |
---
## Project Structure
```
mcp-search-server/
├── src/
│ ├── index.ts # MCP server entry
│ ├── types.ts # Type definitions
│ ├── aggregator.ts # Multi-engine aggregation + deduplication + sorting
│ ├── browser.ts # Headless browser management
│ ├── cache.ts # Disk cache (TTL 5min)
│ ├── circuitBreaker.ts # Engine circuit breaker protection
│ ├── dedupContent.ts # Web page body deduplication
│ ├── filter.ts # Useless information filtering
│ ├── queryExpander.ts # Synonym query expansion
│ ├── queryAdapter.ts # Engine query syntax adaptation
│ ├── fetcher.ts # Web page crawling (Readability)
│ ├── scraper.ts # Anti-scraping shared tool
│ ├── searchContext.ts # Search result session management
│ ├── session.ts # Cookie session management
│ └── engines/
│ ├── bing.ts # Bing
│ ├── baidu.ts # Baidu
│ ├── 360.ts # 360 Search
│ ├── sogou.ts # Sogou
│ ├── duckduckgo.ts # DuckDuckGo
│ ├── brave.ts # Brave Search
│ ├── github.ts # GitHub
│ └── zhihu.ts # Zhihu
├── package.json
├── tsconfig.json
├── README.md #
└── README.en.md # English
```
---
## Usage Examples
```text
Search + crawl combination:
search("Rust language entry tutorial", maxResults: 5)
fetch("https://rustwiki.org/zh-CN/book/")
Specify engine:
search(engines: ["bing", "zhihu"], query: "Vue.js tutorial")
Environment variables:
SEARCH_ENGINES=bing,baidu node build/index.js
```
---
## License
MIT
