English | 中文

兼容 Claude Code、Cursor、Windsurf 和其他 AI 驱动的 IDE

Wuxing Search MCP

基于 SearXNG 的无限制搜索 MCP Server

一个强大的无限制搜索服务器，聚合 100+ 搜索引擎

功能特点 • 快速开始 • 安装 • 使用方法 • 管理命令 • 故障排查

---

什么是 Wuxing Search MCP？

Wuxing Search MCP 是一个基于 SearXNG 构建的强大无限制搜索服务器。它通过模型上下文协议与 Claude Code 无缝集成，通过聚合 100+ 搜索引擎的结果，提供免费且无限制的搜索能力。

为什么选择 Wuxing Search？

传统搜索 API 存在限制：

• ❌ 速率限制和配额
• ❌ 昂贵的 API 成本
• ❌ 单一来源的结果

Wuxing Search 解决了所有这些问题：

• ✅ 完全免费 - 自建 SearXNG，无 API 成本
• ✅ 无限制搜索 - 禁用速率限制器，支持高频搜索
• ✅ 多源聚合 - Google、Bing、DuckDuckGo、Brave 等 100+ 引擎
• ✅ 隐私友好 - 无追踪，无记录
• ✅ MCP 集成 - 完美适配 Claude Code 工作流

---

架构说明

┌─────────────┐      ┌──────────────┐      ┌─────────────┐      ┌─────────────┐
│  你        │ ───▶ │ Claude Code │ ───▶ │ Wuxing      │ ───▶ │  SearXNG    │
│  (用户)    │      │  (MCP 客户端) │      │ Search MCP   │      │ (Docker)    │
└─────────────┘      └──────────────┘      │ (Node.js)   │      │ (Python)    │
                                            └──────────────┘      └─────────────┘
                                                    │
                                                    ▼
                                            ┌───────────────────────────┐
                                            │   搜索引擎聚合 (13+)      │
                                            │   通用: Google, Bing...   │
                                            │   代码: GitHub, HuggingFace│
                                            │   问答: StackOverflow     │
                                            │   包: npm, PyPI           │
                                            │   学术: arXiv             │
                                            │   社区: HN, Reddit        │
                                            │   以及 100+ 更多...       │
                                            └───────────────────────────┘

---

功能特点

✨ 当前功能

• 🔍 无限制网页搜索

  • 无 API 速率限制或配额
  • 支持高频搜索
  • 可配置结果数量（1-100）

• 🌐 多源聚合

  • 通用：Google、Bing、DuckDuckGo、Baidu
  • 代码：GitHub、Hugging Face、GitLab
  • 问答：Stack Overflow
  • 包：npm、PyPI、crates.io、Docker Hub
  • 学术：arXiv、Google Scholar、Semantic Scholar、PubMed
  • 社区：HackerNews、Reddit、Mastodon
  • 文档：MDN
  • 新闻：Google News
  • 支持 100+ 搜索引擎

• 📊 高级搜索选项

  • 时间范围过滤（天、周、月、年）
  • 类别过滤（通用、图片、视频、新闻、IT、科学、文件、社交）
  • 语言过滤
  • 安全搜索级别

• 🔌 MCP 集成

  • 与 Claude Code 无缝集成
  • stdio 通信（MCP 不需要网络端口）
  • JSON-RPC 2.0 协议

• 🐳 简单部署

  • 基于 Docker 的 SearXNG 部署
  • 一键安装
  • 跨平台支持（Windows、macOS、Linux）

• 🔒 隐私优先

  • 无追踪，无记录
  • 自托管，数据不离开你的机器
  • 通过 SearXNG 匿名搜索

---

快速开始

4 个简单步骤即可开始：

前置要求

• Docker（必需）：下载
• Node.js 18+（必需）：下载

1. 克隆项目

git clone https://github.com/MaesHughes/wuxing-search-mcp.git
cd wuxing-search-mcp

2. 安装依赖

npm install

3. 启动 SearXNG

方式 A：使用 Docker 命令（推荐）

docker run -d \
  --name wuxing-searxng \
  --restart unless-stopped \
  -p 18080:8080 \
  -v "$(pwd)/searxng/config:/etc/searxng/" \
  -v "$(pwd)/searxng/data:/var/cache/searxng/" \
  searxng/searxng:latest

方式 B：使用 Docker Compose

docker-compose up -d

4. 配置 Claude Code

找到你的 Claude Code 配置文件：

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS / Linux:

~/.config/Claude/claude_desktop_config.json

第一步：获取你的项目路径

在项目目录下运行以下命令获取绝对路径：

Windows (PowerShell):

Resolve-Path src\index.js

Windows (Git Bash / Bash):

pwd -W && echo "/src/index.js"
# 或手动拼接：$(pwd -W)/src/index.js

macOS / Linux:

pwd && echo "/src/index.js"
# 或手动拼接：$(pwd)/src/index.js

第二步：添加配置

在配置文件中添加以下配置，⚠️ 务必替换 YOUR_FULL_PATH_HERE 为上一步获取的实际路径：

Windows 配置示例

{
  "mcpServers": {
    "wuxing-search": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "D:\\\\path\\\\to\\\\wuxing-search-mcp\\\\src\\\\index.js"
      ],
      "env": {
        "SEARXNG_URL": "http://localhost:18080",
        "MAX_RESULTS": "20",
        "TIMEOUT": "30000"
      }
    }
  }
}

macOS / Linux 配置示例

{
  "mcpServers": {
    "wuxing-search": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/home/username/wuxing-search-mcp/src/index.js"
      ],
      "env": {
        "SEARXNG_URL": "http://localhost:18080",
        "MAX_RESULTS": "20",
        "TIMEOUT": "30000"
      }
    }
  }
}

配置说明：

配置项	Windows	macOS/Linux	说明
type	"stdio"	"stdio"	通信协议类型
command	"cmd"	"node"	Windows 使用 cmd 包装器
args	["/c", "node", "路径..."]	["路径..."]	路径必须使用绝对路径
env.SEARXNG_URL	SearXNG 服务地址	-	默认 http://localhost:18080
env.MAX_RESULTS	默认返回结果数	-	默认 20，范围 1-100
env.TIMEOUT	请求超时时间（毫秒）	-	默认 30000

⚠️ 重要提示：

• Windows 路径中的反斜杠必须转义为双反斜杠 \\\\（JSON 格式要求）
• 或者使用正斜杠 /（Windows 也支持）
• 路径必须是绝对路径，相对路径无法工作
• 修改配置后需要完全重启 Claude Code 才能生效

5. 重启 Claude Code

完全退出并重新打开 Claude Code。

---

使用方法

基础搜索

在 Claude Code 中直接输入：

请搜索最新的 AI 编程工具

高级搜索参数

你也可以指定参数：

请搜索最近一周的 React 教程，返回 10 条结果

可用工具

1. web_search

执行网页搜索并返回结果。

参数	说明	必需	默认值
query	搜索关键词	是	-
max_results	返回结果数量（1-100）	否	20
category	搜索类别	否	general
language	语言代码	否	all
time_range	时间范围过滤器	否	none
safesearch	安全搜索级别（0-2）	否	1

类别选项：

• general - 通用搜索
• images - 图片搜索
• videos - 视频搜索
• news - 新闻搜索
• it - IT 技术
• science - 科学
• files - 文件
• social - 社交媒体

时间范围选项：

• day - 过去 24 小时
• week - 过去一周
• month - 过去一月
• year - 过去一年
• none - 无时间过滤

2. get_server_info

获取搜索服务器状态信息。无参数。

使用示例

示例 1：搜索开源项目

请搜索 GitHub 上热门的 AI agent 项目

示例 2：搜索技术问题

在 Stack Overflow 上搜索 MCP 连接错误的解决方案

示例 3：搜索学术论文

请搜索 arXiv 上关于多智能体协作的最新论文

示例 4：搜索 Python 库

在 PyPI 上搜索 LangChain agents 相关的包

示例 5：搜索开发者讨论

请搜索 HackerNews 上关于 AI 编程的讨论

示例 6：查询服务器状态

查询搜索服务器状态

---

管理命令

NPM 命令

# 查看 SearXNG 状态
npm run status:searxng

# 查看 SearXNG 日志
npm run logs:searxng

# 重启 SearXNG
npm run restart:searxng

# 停止 SearXNG
npm run stop:searxng

# 启动 SearXNG
npm run start:searxng

# 测试搜索服务
npm run test:searxng

Docker 命令

# 查看容器状态
docker ps | grep wuxing-searxng

# 查看实时日志
docker logs -f wuxing-searxng

# 重启服务
docker restart wuxing-searxng

# 停止服务
docker stop wuxing-searxng

# 启动服务
docker start wuxing-searxng

# 删除并重建
docker stop wuxing-searxng && docker rm wuxing-searxng
# 然后重新运行启动命令

---

配置选项

通过环境变量配置 MCP Server：

变量	说明	默认值
SEARXNG_URL	SearXNG 服务地址	http://localhost:18080
MAX_RESULTS	默认返回结果数	20
TIMEOUT	请求超时时间（毫秒）	30000

在 Claude Code 配置的 env 字段中添加这些变量来自定义行为。

---

故障排查

问题 1：搜索工具不显示或报错

检查清单：

1. ✅ SearXNG 容器是否运行？

   docker ps | grep wuxing-searxng
   

2. ✅ SearXNG 服务是否正常？

   curl http://localhost:18080
   

3. ✅ 配置文件路径是否正确（使用绝对路径）？

4. ✅ Node.js 版本是否 >= 18？

   node --version
   

5. ✅ Claude Code 是否已重启？

问题 2：SearXNG 容器无法启动

检查：

1. 端口 18080 是否被占用？

   # Windows
   netstat -ano | findstr :18080
   
   # Linux/Mac
   lsof -ti:18080
   

2. Docker 服务是否运行？

3. 查看容器日志：

   docker logs wuxing-searxng
   

解决方案：

# 删除旧容器并重新创建
docker stop wuxing-searxng && docker rm wuxing-searxng
# 然后重新运行启动命令

问题 3：搜索返回连接错误

可能原因：SearXNG 服务尚未完全启动

解决方案：

# 等待 5-10 秒后重试
# 或重启 SearXNG
docker restart wuxing-searxng

问题 4：结果包含旧内容

原因：时间过滤依赖搜索引擎的支持

解决方案：

1. 使用更短的时间范围（day 而非 week）
2. 在 query 中添加明确的时间关键词（如 2025年1月）
3. 结合使用：

   请搜索 2025年1月的 React 新特性
   

---

技术架构

MCP Server（Node.js）

• 文件：src/index.js
• 依赖：@modelcontextprotocol/sdk, axios
• 通信：stdio（标准输入/输出）
• 作用：实现 MCP 协议，转发请求到 SearXNG

SearXNG（Python/Docker）

• 镜像：searxng/searxng:latest
• 端口：18080（主机）→ 8080（容器）
• 配置：searxng/config/settings.yml
• 数据：searxng/data/（缓存）
• 作用：聚合 100+ 搜索引擎

数据流

用户输入
  → Claude Code
  → MCP Server (stdio)
  → HTTP 请求到 SearXNG
  → 并发请求到各搜索引擎
  → 聚合结果
  → 返回给用户

---

项目结构

wuxing-search-mcp/
├── src/                  # MCP Server 源码
│   └── index.js         # MCP Server 主实现
├── searxng/             # SearXNG 配置
│   ├── config/          # SearXNG settings.yml
│   └── data/            # SearXNG 缓存（自动创建）
├── assets/              # 文档图片
│   └── banner.png       # 项目横幅
├── package.json         # NPM 包配置
├── docker-compose.yml   # Docker Compose 配置
├── install.sh           # Linux/Mac 安装脚本
├── install.ps1          # Windows 安装脚本
├── README.md            # 英文版
├── README.zh-CN.md      # 中文版（本文件）
└── INSTALL.md           # 详细安装指南

---

常见问题

Q: 为什么需要 Docker？

A: SearXNG 是 Python 项目，依赖 50+ 个 Python 包。Docker 提供：

• 避免复杂的手动依赖安装
• 环境隔离
• 简化部署和更新

Q: 可以不用 Docker 吗？

A: 理论上可以，但不推荐。你需要：

1. 安装 Python 3.14
2. 手动安装 50+ Python 依赖
3. 配置 Python 环境

Docker 方案更简单可靠。

Q: 搜索有限额吗？

A: 没有！这是本项目的核心优势：

• 完全自托管
• 无 API 调用限制
• 无请求速率限制

Q: 支持哪些搜索引擎？

A: SearXNG 支持 245 个搜索引擎，默认启用 89 个。

当前已启用的 21 个引擎：

类别	搜索引擎
通用搜索	Google, Bing, DuckDuckGo, Baidu
代码仓库	GitHub, Hugging Face, GitLab
技术问答	Stack Overflow
包管理器	npm, PyPI, crates.io, Docker Hub
学术论文	arXiv, Google Scholar, Semantic Scholar, PubMed
开发者社区	HackerNews, Reddit, Mastodon
开发文档	MDN Web Docs
新闻源	Google News

其他可用引擎（可在配置中启用）：

• 代码：Bitbucket, Codeberg, Gitea, SourceHut
• 包管理：RubyGems, Go, Hex, Packagist
• 社交：Lemmy
• 视频：YouTube, Vimeo, Bilibili
• 等等...

Q: 搜索质量如何？

A: 取决于启用的搜索引擎。默认配置已包含主流搜索引擎，质量较好。如需调整，可编辑 searxng/config/settings.yml。

---

贡献

欢迎社区贡献！你可以这样帮助我们：

1. Fork 本仓库
2. 创建 功能分支（git checkout -b feature/amazing-feature）
3. 提交 更改（git commit -m 'Add amazing feature'）
4. 推送 到分支（git push origin feature/amazing-feature）
5. 打开 Pull Request

贡献方式

• 改进搜索引擎配置
• 为 MCP Server 添加新功能
• 报告 bug 和问题
• 建议新功能
• 改进文档
• 分享你的反馈

---

资源

📚 文档

• 安装指南 - 详细安装说明
• SearXNG 文档 - SearXNG 官方文档
• MCP 规范 - 模型上下文协议

🌐 官方网站

• Wuxing Codes 博客 - 最新更新和教程

💬 社区

• GitHub Issues - 报告问题
• GitHub Discussions - 提问

---

许可证

MIT License - 详见 LICENSE 文件。

---

致谢

• 基于开源项目 SearXNG 构建
• 为 Claude Code 社区打造
• 属于 Wuxing Codes 生态系统的一部分

---