Wuxing Search MCP

What is Wuxing Search MCP?

Wuxing Search MCP is a powerful, unlimited search server built on SearXNG. It integrates seamlessly with Claude Code via the Model Context Protocol, providing free and unlimited search capabilities by aggregating results from 100+ search engines.

Why choose Wuxing Search?

Traditional search APIs have limitations:

• ❌ Rate limits and quotas

• ❌ Expensive API costs

• ❌ Single-source results

Wuxing Search solves all these problems:

• ✅ Completely Free - Self-hosted SearXNG, no API costs

• ✅ Unlimited Search - Rate limiters disabled, supports high-frequency searching

• ✅ Multi-source Aggregation - 100+ engines including Google, Bing, DuckDuckGo, Brave, etc.

• ✅ Privacy-Friendly - No tracking, no logging

• ✅ MCP Integration - Perfectly adapted for Claude Code workflows

Related MCP server: SearXNG MCP Server

Architecture Overview

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

Features

✨ Current Features

• 🔍 Unlimited Web Search

  • No API rate limits or quotas

  • Supports high-frequency searching

  • Configurable result count (1-100)

• 🌐 Multi-source Aggregation

  • General: Google, Bing, DuckDuckGo, Baidu

  • Code: GitHub, Hugging Face, GitLab

  • Q&A: Stack Overflow

  • Packages: npm, PyPI, crates.io, Docker Hub

  • Academic: arXiv, Google Scholar, Semantic Scholar, PubMed

  • Community: HackerNews, Reddit, Mastodon

  • Documentation: MDN

  • News: Google News

  • Supports 100+ search engines

• 📊 Advanced Search Options

  • Time range filtering (day, week, month, year)

  • Category filtering (general, images, videos, news, IT, science, files, social)

  • Language filtering

  • Safe search levels

• 🔌 MCP Integration

  • Seamless integration with Claude Code

  • stdio communication (MCP does not require network ports)

  • JSON-RPC 2.0 protocol

• 🐳 Simple Deployment

  • Docker-based SearXNG deployment

  • One-click installation

  • Cross-platform support (Windows, macOS, Linux)

• 🔒 Privacy First

  • No tracking, no logging

  • Self-hosted, data never leaves your machine

  • Anonymous searching via SearXNG

Quick Start

Get started in 4 simple steps:

Prerequisites

• Docker (Required): Download

• Node.js 18+ (Required): Download

1. Clone the project

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

2. Install dependencies

npm install

3. Start SearXNG

Method A: Using Docker command (Recommended)

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

Method B: Using Docker Compose

docker-compose up -d

4. Configure Claude Code

Locate your Claude Code configuration file:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS / Linux:

~/.config/Claude/claude_desktop_config.json

Step 1: Get your project path

Run the following command in the project directory to get the absolute path:

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

Step 2: Add configuration

Add the following configuration to your config file, ⚠️ Be sure to replace YOUR_FULL_PATH_HERE with the actual path obtained in the previous step:

Windows Configuration Example

{
  "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 Configuration Example

{
  "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"
      }
    }
  }
}

Configuration Notes:

⚠️ Important Note:

• Backslashes in Windows paths must be escaped as double backslashes \\ (JSON format requirement)

• Alternatively, use forward slashes / (Windows supports this too)

• Paths must be absolute; relative paths will not work

• You must fully restart Claude Code for configuration changes to take effect

5. Restart Claude Code

Fully exit and reopen Claude Code.

Usage

Basic Search

Type directly in Claude Code:

请搜索最新的 AI 编程工具

Advanced Search Parameters

You can also specify parameters:

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

Available Tools

1. web_search

Perform a web search and return results.

Category Options:

• general - General search

• images - Image search

• videos - Video search

• news - News search

• it - IT technology

• science - Science

• files - Files

• social - Social media

Time Range Options:

• day - Past 24 hours

• week - Past week

• month - Past month

• year - Past year

• none - No time filter

2. get_server_info

Get search server status information. No parameters.

Usage Examples

Example 1: Search for open source projects

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

Example 2: Search for technical issues

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

Example 3: Search for academic papers

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

Example 4: Search for Python libraries

在 PyPI 上搜索 LangChain agents 相关的包

Example 5: Search for developer discussions

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

Example 6: Query server status

查询搜索服务器状态

Management Commands

NPM Commands

# 查看 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 Commands

# 查看容器状态
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
# 然后重新运行启动命令

Configuration Options

Configure the MCP Server via environment variables:

Add these variables to the env field in your Claude Code configuration to customize behavior.

Troubleshooting

Issue 1: Search tool not showing or throwing errors

Checklist:

1. ✅ Is the SearXNG container running?

   docker ps | grep wuxing-searxng

2. ✅ Is the SearXNG service working properly?

   curl http://localhost:18080

3. ✅ Is the config file path correct (using absolute path)?

4. ✅ Is Node.js version >= 18?

   node --version

5. ✅ Has Claude Code been restarted?

Issue 2: SearXNG container fails to start

Check:

1. Is port 18080 occupied?

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

2. Is the Docker service running?

3. Check container logs:

   docker logs wuxing-searxng

Solution:

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

Issue 3: Search returns connection error

Possible cause: SearXNG service has not fully started

Solution:

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

Issue 4: Results contain outdated content

Reason: Time filtering depends on search engine support

Solution:

1. Use a shorter time range (day instead of week)

2. Add explicit time keywords to the query (e.g., January 2025)

3. Combine usage:

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

Technical Architecture

MCP Server (Node.js)

• File: src/index.js

• Dependencies: @modelcontextprotocol/sdk, axios

• Communication: stdio (Standard Input/Output)

• Role: Implements MCP protocol, forwards requests to SearXNG

SearXNG (Python/Docker)

• Image: searxng/searxng:latest

• Port: 18080 (host) → 8080 (container)

• Config: searxng/config/settings.yml

• Data: searxng/data/ (cache)

• Role: Aggregates 100+ search engines

Data Flow

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

Project Structure

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           # 详细安装指南

FAQ

Q: Why is Docker needed?

A: SearXNG is a Python project that depends on 50+ Python packages. Docker provides:

• Avoids complex manual dependency installation

• Environment isolation

• Simplifies deployment and updates

Q: Can I use it without Docker?

A: Theoretically yes, but not recommended. You would need to:

1. Install Python 3.14

2. Manually install 50+ Python dependencies

3. Configure the Python environment

The Docker approach is simpler and more reliable.

Q: Are there search limits?

A: No! This is the core advantage of this project:

• Completely self-hosted

• No API call limits

• No request rate limits

Q: Which search engines are supported?

A: SearXNG supports 245 search engines, with 89 enabled by default.

Currently enabled 21 engines:

Other available engines (can be enabled in config):

• Code: Bitbucket, Codeberg, Gitea, SourceHut

• Package Management: RubyGems, Go, Hex, Packagist

• Social: Lemmy

• Video: YouTube, Vimeo, Bilibili

• And more...

Q: How is the search quality?

A: Depends on the enabled search engines. The default configuration already includes mainstream search engines, providing good quality. If adjustments are needed, you can edit searxng/config/settings.yml.

Contributing

Community contributions are welcome! You can help us by:

1. Fork this repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

How to contribute

• Improve search engine configuration

• Add new features to the MCP Server

• Report bugs and issues

• Suggest new features

• Improve documentation

• Share your feedback

Resources

📚 Documentation

• Installation Guide - Detailed installation instructions

• SearXNG Documentation - Official SearXNG documentation

• MCP Specification - Model Context Protocol

🌐 Official Website

• Wuxing Codes Blog - Latest updates and tutorials

💬 Community

• GitHub Issues - Report issues

• GitHub Discussions - Ask questions

License

MIT License - See the LICENSE file for details.

Acknowledgments

• Built on the open-source project SearXNG

• Created for the Claude Code community

• Part of the Wuxing Codes ecosystem

Made with ❤️ by the Wuxing Team

⭐ Star us on GitHub — it really helps!