English | 中文

Compatible with Claude Code, Cursor, Windsurf, and other AI-powered IDEs

Wuxing Search MCP

Unlimited Search MCP Server Powered by SearXNG

A powerful, unlimited search server that aggregates 100+ search engines

Features • Quick Start • Installation • Usage • Management • Troubleshooting

What is Wuxing Search MCP?

Wuxing Search MCP is a powerful, unlimited search server built on top of 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 Wuxing Search?

Traditional search APIs have limitations:

• ❌ Rate limits and quotas
• ❌ Expensive API costs
• ❌ Single source results

Wuxing Search solves all of this:

• ✅ Completely Free - Self-hosted SearXNG, no API costs
• ✅ Unlimited Searches - Rate limiter disabled for high-frequency searching
• ✅ Multi-Source Aggregation - Google, Bing, DuckDuckGo, Brave, and 100+ engines
• ✅ Privacy Friendly - No tracking, no logging
• ✅ MCP Integrated - Perfect for Claude Code workflow

Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐      ┌─────────────┐
│  You        │ ───▶ │ Claude Code │ ───▶ │ Wuxing      │ ───▶ │  SearXNG    │
│  (User)     │      │  (MCP Client) │      │ Search MCP   │      │ (Docker)    │
└─────────────┘      └──────────────┘      │ (Node.js)   │      │ (Python)    │
                                            └──────────────┘      └─────────────┘
                                                    │
                                                    ▼
                                            ┌───────────────────────────┐
                                            │   Search Engine Aggregator│
                                            │   - Google               │
                                            │   - Bing                 │
                                            │   - DuckDuckGo           │
                                            │   - Brave                │
                                            │   - Wikipedia            │
                                            │   - And 100+ more...     │
                                            └───────────────────────────┘

Features

✨ Current Features

• 🔍 Unlimited Web Search

  • No API rate limits or quotas
  • Support for high-frequency searching
  • Configurable result count (1-100)

• 🌐 Multi-Source Aggregation

  • Google, Bing, DuckDuckGo, Brave
  • Wikipedia, GitHub, Stack Overflow
  • 100+ search engines supported

• 📊 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 Claude Code integration
  • stdio communication (no network ports for MCP)
  • JSON-RPC 2.0 protocol

• 🐳 Easy Deployment

  • Docker-based SearXNG deployment
  • One-command installation
  • Cross-platform support (Windows, macOS, Linux)

• 🔒 Privacy First

  • No tracking, no logging
  • Self-hosted, data never leaves your machine
  • Anonymous search requests 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

Option A: Using Docker Command (Recommended)

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

Option B: Using Docker Compose

docker-compose up -d

4. Configure Claude Code

Find your Claude Code config file:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS / Linux:

~/.config/Claude/claude_desktop_config.json

Add the following configuration (update the path to your actual project location):

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

Important:

• Replace D:\\path\\to\\wuxing-search-mcp\\src\\index.js with your actual project path
• Windows paths use double backslashes \\
• macOS/Linux paths use forward slashes /

5. Restart Claude Code

Completely quit and reopen Claude Code.

Usage

Basic Search

Simply ask in Claude Code:

Search for the latest AI programming tools

Advanced Search with Parameters

You can specify parameters:

Search for React tutorials from the past week, return 10 results

Available Tools

1. web_search

Execute web searches 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 Documentation

Search for OpenCode official documentation and tutorials

Example 2: Search Latest Content

Search for articles about AI Agent from the past week

Example 3: Search Specific Category

Search for Python machine learning library video tutorials

Example 4: Check Server Status

Check search server status

Management

NPM Commands

# View SearXNG status
npm run status:searxng

# View SearXNG logs
npm run logs:searxng

# Restart SearXNG
npm run restart:searxng

# Stop SearXNG
npm run stop:searxng

# Start SearXNG
npm run start:searxng

# Test search service
npm run test:searxng

Docker Commands

# View container status
docker ps | grep wuxing-searxng

# View real-time logs
docker logs -f wuxing-searxng

# Restart service
docker restart wuxing-searxng

# Stop service
docker stop wuxing-searxng

# Start service
docker start wuxing-searxng

# Delete and recreate
docker stop wuxing-searxng && docker rm wuxing-searxng
# Then re-run the start command

Configuration

Configure the MCP Server through environment variables:

Add these variables in the env field of your Claude Code configuration.

Troubleshooting

Problem 1: Search Tool Not Showing or Error

Checklist:

1. ✅ Is SearXNG container running?

   docker ps | grep wuxing-searxng
   

2. ✅ Is SearXNG service healthy?

   curl http://localhost:8888
   

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

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

   node --version
   

5. ✅ Has Claude Code been restarted?

Problem 2: SearXNG Container Won't Start

Check:

1. Is port 8888 occupied?

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

2. Is Docker service running?

3. View container logs:

   docker logs wuxing-searxng
   

Solution:

# Delete old container and recreate
docker stop wuxing-searxng && docker rm wuxing-searxng
# Then re-run the start command

Problem 3: Search Returns Connection Error

Possible Cause: SearXNG service not fully started

Solution:

# Wait 5-10 seconds and retry
# Or restart SearXNG
docker restart wuxing-searxng

Problem 4: Results Contain Old Content

Cause: Time filtering depends on search engine support

Solution:

1. Use shorter time ranges (day instead of week)
2. Add explicit time keywords in query (e.g., January 2025)
3. Combine both approaches:

   Search for React new features in January 2025
   

Technical Architecture

MCP Server (Node.js)

• File: src/index.js
• Dependencies: @modelcontextprotocol/sdk, axios
• Communication: stdio (standard input/output)
• Role: Implement MCP protocol, forward requests to SearXNG

SearXNG (Python/Docker)

• Image: searxng/searxng:latest
• Port: 8888 (host) → 8080 (container)
• Config: searxng/config/settings.yml
• Data: searxng/data/ (cache)
• Role: Aggregate 100+ search engines

Data Flow

User Input
  → Claude Code
  → MCP Server (stdio)
  → HTTP request to SearXNG
  → Parallel requests to search engines
  → Aggregate results
  → Return to user

Project Structure

wuxing-search-mcp/
├── src/                  # MCP Server source
│   └── index.js         # Main MCP Server implementation
├── searxng/             # SearXNG configuration
│   ├── config/          # SearXNG settings.yml
│   └── data/            # SearXNG cache (auto-created)
├── assets/              # Documentation images
│   └── banner.png       # Project banner
├── package.json         # NPM package configuration
├── docker-compose.yml   # Docker Compose configuration
├── install.sh           # Linux/Mac installation script
├── install.ps1          # Windows installation script
├── README.md            # This file (English)
├── README.zh-CN.md      # Chinese version
└── INSTALL.md           # Detailed installation guide

FAQ

Q: Why is Docker required?

A: SearXNG is a Python project with 50+ Python package dependencies. Docker provides:

• Avoid complex manual dependency installation
• Environment isolation
• Simplified deployment and updates

Q: Can I skip Docker?

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

1. Install Python 3.14
2. Manually install 50+ Python dependencies
3. Configure Python environment

The Docker approach is much 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 100+ search engines, including:

• General: Brave, DuckDuckGo, Google, Bing
• Encyclopedia: Wikipedia, Brave Encyclopedia
• Tech: GitHub, Stack Overflow, NPM
• Video: YouTube, Dailymotion, Vimeo
• Files: KickassTorrent, 1337x
• And many more...

Q: How is search quality?

A: Depends on enabled search engines. Default configuration includes mainstream search engines with good quality. To adjust, edit searxng/config/settings.yml.

Contributing

We welcome contributions from the community! Here's how you can help:

1. Fork the 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

Ways to Contribute

• Improve search engine configurations
• Add new features to 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 docs
• MCP Specification - Model Context Protocol

🌐 Official Website

• Wuxing Codes Blog - Latest updates and tutorials

💬 Community

• GitHub Issues - Report bugs
• GitHub Discussions - Ask questions

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built on top of SearXNG - An open-source metasearch engine
• Built for the Claude Code community
• Part of the Wuxing Codes ecosystem