search-mcp-server/README.md

search-mcp

MCP server for web and code search using SearXNG (privacy-respecting metasearch) and Grep.app (GitHub code search).

Version 2.0.0 - Now with auto-managed local SearXNG!

🎯 Tavily Alternative: Free, local, privacy-respecting search - no API keys, no external dependencies, no cost!

What's New in v2.0.0

🎉 Fully Self-Contained Search - No external SearXNG instance needed!

• ✅ Auto-starts SearXNG Docker container on first search
• ✅ Keeps SearXNG running for fast subsequent searches
• ✅ Local-only - all searches stay on your machine
• ✅ Privacy-first - queries multiple engines without tracking
• ✅ Zero configuration - works out of the box

Features

Web Search (via SearXNG)

• searxng_search - General web search with multiple categories
• searxng_image_search - Image search
• searxng_news_search - News search
• searxng_engines_info - List available search engines

Code Search (via Grep.app)

• grep_search - Search code across public GitHub repos
• github_file - Fetch single file from GitHub
• github_batch_files - Fetch multiple files in parallel

Management Tools

• search_status - Check status of all search services
• searxng_start - Manually start SearXNG container
• searxng_stop - Stop SearXNG to free resources
• searxng_config - View default SearXNG configuration

vs Tavily (and other paid search APIs)

Feature	Tavily	search-mcp v2
Cost	Paid API ($$/month)	Free forever
Privacy	Sends queries to external service	100% local - searches stay on your machine
API Keys	Required	None needed
Rate Limits	Yes	Unlimited
Offline	No	Works offline (with cached results)
Setup	Sign up, get API key	Install Docker, run binary

Bottom line: If you want privacy, zero cost, and zero configuration - use search-mcp v2.

Quick Start

Prerequisites

• Docker must be installed

Download & Run

# Clone and build from source
git clone https://github.com/yourusername/search-mcp
cd search-mcp
make build

# Or download release (coming soon)
# curl -L https://github.com/yourusername/search-mcp/releases/download/v2.0.0/search-mcp-$(uname -s)-$(uname -m) -o search-mcp
# chmod +x search-mcp

# Run with stdio (for MCP clients like Claude Desktop, Cursor)
./go_mcp_server_searxng -t stdio

MCP Client Configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "search": {
      "command": "/path/to/search-mcp",
      "args": ["-t", "stdio"]
    }
  }
}

Cursor (Settings > MCP):

{
  "mcpServers": {
    "search": {
      "command": "/path/to/search-mcp",
      "args": ["-t", "stdio"]
    }
  }
}

How It Works

User asks for search
        ↓
MCP Server checks if SearXNG running
        ↓
    ┌─── No ───┐
    ↓          │
Auto-start    │
Docker container
    ↓          │
Wait for ready│
    ↓          │
    └──── Yes ─┘
        ↓
  Execute search
        ↓
  Return results

First search: ~10-15 seconds (includes container startup)

Subsequent searches: ~1-2 seconds (instant response)

Command-Line Options

Flag	Default	Description
-t	stdio	Transport type: stdio or sse
-h	0.0.0.0	Host for SSE server
-p	8892	Port for SSE server
-searxng	http://127.0.0.1:8080	SearXNG URL (for external instance)
-searxng-autostart	true	Auto-start SearXNG container
-searxng-image	searxng/searxng:latest	Docker image to use
-searxng-port	8080	Port for SearXNG container
-searxng-stop-on-exit	false	Stop container when MCP server exits
-searxng-timeout	60	Seconds to wait for SearXNG ready

Examples

# Default: auto-start SearXNG, keep running after exit
./search-mcp -t stdio

# Stop SearXNG when MCP exits (saves RAM)
./search-mcp -t stdio -searxng-stop-on-exit

# Use external SearXNG instance (skip auto-start)
./search-mcp -t stdio -searxng https://searx.example.com

# SSE mode with custom port
./search-mcp -t sse -p 3000

Resource Usage

Component	Memory	CPU	Notes
MCP Server	~10MB	Negligible	Very lightweight
SearXNG	~200-300MB	Low idle	Containerized metasearch
Total	~250MB	Bursty	Reasonable for modern machines

Privacy & Security

• ✅ All searches local - Nothing leaves your machine except to search engines
• ✅ No tracking - SearXNG aggregates results without personalization
• ✅ No API keys needed - Uses public search engines
• ✅ Docker isolation - SearXNG runs in container with no host access

Default engines: DuckDuckGo, Brave, Bing, Wikipedia, GitHub, StackOverflow

Troubleshooting

"Docker is not available"

Install Docker: https://docs.docker.com/get-docker/

"Port 8080 is already in use"

# Use a different port
./search-mcp -t stdio -searxng-port 8081

SearXNG won't start

# Check Docker is running
docker ps

# Check logs
docker logs searxng-mcp-local

# Reset: remove container
docker rm -f searxng-mcp-local

Search is slow

First search is slow (container startup). If consistently slow:

• Check internet connection
• Try different engines in search queries
• Check search_status tool output

Building from Source

# Clone repo
git clone https://github.com/yourusername/search-mcp
cd search-mcp

# Build
go build -o go_mcp_server_searxng .

# Or cross-compile
make build-all

Architecture

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                           │
│              (Claude Desktop, Cursor, etc.)            │
└─────────────────────────────────────────────────────────┘
                          │
                          │ stdio/SSE
                          ▼
┌─────────────────────────────────────────────────────────┐
│                 search-mcp (Go)                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Auto-start logic                                │  │
│  │  • Check if SearXNG running                      │  │
│  │  • Start Docker container if needed              │  │
│  │  • Wait for health check                        │  │
│  └──────────────────────────────────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │   Search    │  │   Image   │  │    News     │      │
│  │   Tools     │  │   Search  │  │   Search    │      │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘      │
│         └─────────────────┼─────────────────┘           │
│                           │                           │
│  ┌─────────────┐         │         ┌─────────────┐     │
│  │   Grep.app  │◄────────┴────────►│  SearXNG    │     │
│  │  (GitHub)   │                   │  (Docker)   │     │
│  └─────────────┘                   └─────────────┘     │
└─────────────────────────────────────────────────────────┘

License

MIT