🔍 SearXNG MCP Server
A privacy-focused Model Context Protocol (MCP) server that provides Claude with web search capabilities through SearXNG metasearch engine.
✨ Features
- 🔒 Privacy-first - No tracking, no data collection via SearXNG
- 🌐 Multi-engine - Aggregates results from Google, Bing, DuckDuckGo, Brave, and more
- 🎯 Specialized search - Web, images, videos, and news search
- ⚡ Fast - Optimized with minimal tool set (4 tools)
- 🐳 Docker included - SearXNG instance setup included
- 🛠️ Easy setup - Python-based with UV package manager
📦 Installation
Prerequisites
- Python 3.10 or higher
- Docker and Docker Compose
- Git
Quick Install
1. Clone repository:
git clone https://github.com/netixc/SearxngMCP.git
cd SearxngMCP
2. Configure SearXNG:
Edit the following files with your settings:
docker-compose.yml- ReplaceYOUR_IPwith your server's IP addressdocker-compose.yml- ReplaceCHANGE_THIS_SECRET_KEYwith a secret keysearxng/settings.yml- ReplaceCHANGE_THIS_TO_YOUR_OWN_SECRET_KEYwith the same secret keysearxng-config/config.json- ReplaceYOUR_IPwith your server's IP address
Generate a secret key:
openssl rand -hex 32
3. Start SearXNG instance:
docker compose up -d
SearXNG will be available at http://YOUR_IP:8080
4. Install MCP server (using UV - recommended):
# Create venv and install
uv venv
source .venv/bin/activate # Linux/macOS
uv pip install -e ".[dev]"
5. Verify installation:
# Check SearXNG is running
curl http://YOUR_IP:8080
⚙️ Configuration
MCP Client Setup
Add to your MCP settings (e.g., Claude Desktop config):
{
"mcpServers": {
"searxng": {
"command": "/absolute/path/to/SearxngMCP/run-server.sh"
}
}
}
SearXNG Configuration
The SearXNG instance is configured via searxng/settings.yml:
- Default engines: Google, Bing, DuckDuckGo, Brave, Wikipedia, YouTube
- JSON API enabled for MCP access
- Privacy features enabled (no tracking)
- Accessible on your LAN at YOUR_IP:8080
IMPORTANT: Before starting Docker, replace the following in your config files:
docker-compose.yml: ReplaceYOUR_IPandCHANGE_THIS_SECRET_KEYsearxng/settings.yml: ReplaceCHANGE_THIS_TO_YOUR_OWN_SECRET_KEYsearxng-config/config.json: ReplaceYOUR_IP
Generate secret key: openssl rand -hex 32
MCP Server Configuration
Edit searxng-config/config.json (replace YOUR_IP with your server's IP):
{
"searxng": {
"url": "http://YOUR_IP:8080",
"timeout": 10
},
"logging": {
"level": "INFO",
"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
"file": null
}
}
🔧 Available Tools
The server provides 3 optimized tools designed for efficient research:
1. search - Quick Web/News Search
Quick single search for web or news content.
Use when:
- Need quick information or simple lookup
- User asks for a basic web search
- Looking for news on a topic
Parameters:
query*- What to search forcategory- "general" (default) or "news"engines- Optional: Specific engines (e.g., "google,bing")max_results- Number of results (default: 10, max: 50)
Example:
User: What's the latest Python release?
Claude: [Calls search("latest Python release", category="general")]
2. search_media - Images & Videos
Search for images or videos.
Use when:
- User wants to find images or photos
- Looking for video content
- "show me pictures of..." or "find videos about..."
Parameters:
query*- What to findmedia_type- "images" (default) or "videos"engines- Optional: Specific enginesmax_results- Number of results (default: 10, max: 50)
Example:
User: Show me pictures of Northern Lights
Claude: [Calls search_media("Northern Lights", media_type="images")]
3. research_topic - Deep Research ⭐
Multi-search research with automatic analysis and synthesis.
Use when:
- User wants comprehensive research or briefing
- Need to validate information across multiple sources
- User asks to "research", "investigate", or "analyze"
- Creating detailed reports with cross-referenced sources
What it does:
- Runs 2-6 searches automatically using different strategies
- Searches multiple engines (Google, Bing, DuckDuckGo, Brave, Wikipedia)
- Combines general web + news sources
- Deduplicates results across all searches
- Returns 15-50 UNIQUE sources
- Instructs Claude to analyze and synthesize (not just list sources)
Critical behavior: After gathering sources, Claude is instructed to:
- Read and analyze ALL sources
- Cross-reference claims across sources
- Identify high-confidence facts (confirmed by many sources)
- Note contradictions or single-source claims
- Create comprehensive briefing with executive summary
- Assess source quality and credibility
Parameters:
query*- Research topic or questiondepth- Research thoroughness:"quick"- 2 searches, ~15 unique sources"standard"- 4 searches, ~30 unique sources (recommended)"deep"- 6 searches, ~50 unique sources
Example:
User: Research the latest AI developments and give me a briefing
Claude: [Calls research_topic("latest AI developments 2025", depth="standard")]
Claude receives 32 unique sources, then synthesizes:
"# AI Developments Briefing (2025)
## Executive Summary
Based on analysis of 32 sources from Google, Bing, DuckDuckGo, and Wikipedia...
## Key Findings
✓ Major development 1 (HIGH CONFIDENCE - confirmed by 12 sources)
✓ Emerging trend 2 (MEDIUM - reported by 5 sources)
⚠ Claim 3 (LOW - single source, needs verification)
## Contradictions
Source A says X, but Sources B, C, D report Y...
## Source Quality
Most reliable: Google News (8 sources), Wikipedia (3 sources)
..."
💡 Usage Examples
General search:
User: What is the latest news about AI?
Claude: [Calls search("latest AI news")]
Image search:
User: Show me pictures of Northern Lights
Claude: [Calls search_images("Northern Lights")]
Video search:
User: Find Python tutorial videos
Claude: [Calls search_videos("Python tutorial")]
News search:
User: What's happening with climate change?
Claude: [Calls search_news("climate change")]
🐳 Docker Management
Start SearXNG:
docker-compose up -d
Stop SearXNG:
docker-compose down
View logs:
docker-compose logs -f searxng
Rebuild:
docker-compose down
docker-compose up -d --build
🛠️ Development
Run tests:
pytest
Format code:
black .
Type checking:
mypy .
Lint:
ruff .
🎯 Why Only 4 Tools?
This MCP server is optimized for efficiency:
- Focused functionality - Each tool has a clear, distinct purpose
- LLM-friendly - Tool descriptions include "Use this when..." guidance
- Low context - Minimal tool set reduces token usage
- Privacy-first - SearXNG aggregates without tracking
Unlike direct search engine APIs, SearXNG provides:
- Privacy protection (no tracking)
- Multi-engine aggregation
- Self-hosted control
- No API keys needed
📁 Project Structure
SearxngMCP/
├── docker-compose.yml # SearXNG Docker setup
├── searxng/
│ └── settings.yml # SearXNG configuration
├── src/searxng_mcp/
│ ├── server.py # Main MCP server
│ ├── config/ # Configuration handling
│ │ ├── models.py
│ │ └── loader.py
│ └── tools/ # Search tool implementations
│ └── search.py
├── searxng-config/
│ └── config.json # MCP configuration
├── run-server.sh # Server startup script
├── pyproject.toml # Dependencies
└── README.md
📄 License
MIT License
🙏 Credits
- SearXNG - Privacy-respecting metasearch engine
- Model Context Protocol - MCP specification
- Built with FastMCP