Content
# Claude Web Search MCP Server 🔍
MCP Server providing web search and scraping capabilities for Claude, **Extreme China Edition** - supporting multiple domestic search engines, parallel search, and intelligent deduplication.
## ✨ Features
- 🇨🇳 **Domestic Search Engines** - Baidu, Sogou, 360, Bing Chinese
- 🌐 **International Search Engines** - DuckDuckGo, Bing, SerpAPI
- 🔄 **Intelligent Fallback** - Automatic switch to backup source if primary source fails
- ⚡ **Parallel Search** - Supports parallel queries across multiple engines
- 📝 **Search + Scraping** - Returns complete article content in one step (benchmarked against Firecrawl)
- ⚙️ **YAML Configuration** - Centralized management of all configurations
- 🔐 **Security Hardening** - Rate Limit, API Key, audit logs
- 🖥️ **Cross-Platform Script** - Supports Windows and Linux
---
## 🚀 Quick Start
### 1. Install Dependencies
```bash
cd claude-web-search-mcp
npm install
npm run build
```
### 2. Configuration
Edit `config.yaml`:
```yaml
server:
port: 3001
api_key: "your-strong-api-key"
search:
providers:
- name: baidu
enabled: true
- name: sogou
enabled: true
- name: zh360
enabled: true
- name: duckduckgo
enabled: true
strategy:
mode: "priority" # priority or parallel
deduplication: true # result deduplication
```
### 3. Start Service
**Windows:**
```powershell
.\server.bat start # start (no black window)
.\server.bat stop # stop
.\server.bat restart # restart
.\server.bat status # status
.\server.bat logs # logs
```
**Linux:**
```bash
chmod +x server.sh
./server.sh start
./server.sh stop
./server.sh restart
./server.sh status
./server.sh logs
```
---
## 🔍 Supported Search Engines
| Engine | Type | Description |
|------|------|------|
| **Baidu** | Domestic | Directly usable in China, no API Key required |
| **Sogou** | Domestic | Directly usable in China |
| **360** | Domestic | Directly usable in China |
| **Bing Chinese** | Domestic | cn.bing.com, backup |
| **DuckDuckGo** | International | HTML search, free |
| **Bing** | International | Requires API Key |
| **SerpAPI** | International | Requires API Key |
---
## 📡 Usage
### Method 1: Claude Code (MCP)
```bash
claude mcp add -t http -H "x-api-key:your-api-key" -s user web-search http://127.0.0.1:3001/mcp
```
In Claude Code:
```
Search for the latest AI news
Search for Python tutorials and return article content
```
### Method 2: REST API
**Basic Search**:
```bash
curl -X POST http://localhost:3001/api/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"query": "AI news", "num_results": 5}'
```
**Search + Scrape Content**:
```bash
curl -X POST http://localhost:3001/api/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"query": "Python tutorial", "fetch_content": true}'
```
---
## 📋 API Reference
### POST /api/search
| Parameter | Type | Default | Description |
|------|------|--------|------|
| query | string | required | search query |
| num_results | number | 5 | number of results to return (max 20) |
| fetch_content | boolean | false | whether to scrape complete content |
| scrape_limit | number | 3 | number of results to scrape content for (max 5) |
### POST /api/scrape
| Parameter | Type | Default | Description |
|------|------|--------|------|
| url | string | required | URL to scrape |
| extract_links | boolean | true | whether to extract links |
| extract_images | boolean | false | whether to extract images |
---
## 🔧 Configuration Instructions
### Complete config.yaml Configuration
```yaml
server:
port: 3001
host: "0.0.0.0"
api_key: "your-api-key"
security:
rate_limit:
window_ms: 60000
max_requests: 1000
cors:
enabled: true
origin: "*"
search:
providers:
- name: baidu
enabled: true
- name: sogou
enabled: true
- name: zh360
enabled: true
- name: duckduckgo
enabled: true
strategy:
mode: "priority" # priority | parallel
timeout_ms: 15000
deduplication: true
scraping:
user_agent: "Mozilla/5.0 ..."
timeout_ms: 10000
max_content_length: 100000
logging:
level: "info"
file:
enabled: true
path: "./logs/app.log"
audit:
enabled: true
```
---
## 📁 Project Structure
```
claude-web-search-mcp/
├── src/
│ ├── mcp-http-server.ts # MCP HTTP server
│ ├── config.ts # configuration loading
│ ├── tools/ # MCP tools
│ ├── providers/ # search engines
│ │ ├── baidu.ts
│ │ ├── sogou.ts # Sogou
│ │ ├── zh360.ts # 360 Search
│ │ ├── bingCN.ts # Bing Chinese
│ │ ├── duckduckgo.ts
│ │ └── ...
│ └── utils/
│ ├── html.ts
│ └── logger.ts
├── config.yaml
├── server.bat
├── server.ps1
├── server.sh
└── README.md
```
---
## 📝 Update Log
### v1.2.0 (2026-03-27)
- ✅ Added domestic search engines: Sogou, 360, Bing Chinese
- ✅ Supports parallel search strategy
- ✅ Automatic result deduplication
- ✅ Improved logging system (Shanghai timezone)
- ✅ Updated documentation
### v1.1.0
- ✅ Added `fetch_content` parameter
- ✅ Configuration migrated to `config.yaml`
- ✅ Security hardening
### v1.0.0
- Initial version
---
## 📄 License
MIT
