MCP SearXNG Go

A high-performance Model Context Protocol (MCP) server implementation in Go that provides AI assistants with privacy-focused web search capabilities through SearXNG.

Built with the official MCP Go SDK maintained in collaboration with Google.

Features

• 🔍 Web Search: Powered by SearXNG metasearch engine with support for 70+ search engines
• 🌐 URL Content Extraction: Fetch and convert web pages to Markdown
• 🔒 Privacy-Focused: All searches go through your own SearXNG instance
• ⚡ High Performance: Built in Go with in-memory caching (60s TTL)
• 🐳 Docker Ready: One-command deployment with docker-compose
• 🛡️ Secure: Non-root container execution, size limits, request timeouts

Quick Start

Prerequisites

• Docker and Docker Compose
• Go 1.25+ (for local development)

Using Docker (Recommended)

1. Clone the repository:

   git clone https://github.com/Tomlord1122/mcp-searxng-claude-go.git
   cd mcp-searxng-claude-go
   

2. Create environment file:

   cp .env.example .env
   echo "SEARXNG_SECRET=$(openssl rand -hex 16)" >> .env
   

3. Start services:

   # Build and start both SearXNG and MCP server
   docker compose up -d
   
   # Or use convenience script
   ./start-mcp.sh
   

4. Verify it's running:

   docker compose logs -f mcp-searxng-go
   

5. Setup your environment to use it in Claude Code Create a file with this name ~/.mcp.json

   {
     "mcpServers": {
       "searxng": {
         "command": "docker",
         "args": ["exec", "-i", "mcp-searxng-go", "/app/mcp-searxng-go"],
         "env": {
           "SEARXNG_URL": "http://searxng:8080"
         }
       }
     }
   }
   

   Add this to ~/.claude/settings.json

   {
    "permissions": {
    "allow": [
      "mcp__searxng__searxng_web_search",
      "mcp__searxng__web_url_read"
    ]
    },
    "enabledMcpjsonServers": [
      "searxng"
    ]
    }
   
   

Local Development

1. Install dependencies:

   make deps
   

2. Build the binary:

   make build
   

3. Run locally:

   # Requires a running SearXNG instance
   SEARXNG_URL=http://localhost:8080 ./mcp-searxng-go
   

MCP Tools

1. searxng_web_search

Performs web searches using SearXNG.

Parameters:

• query (required): Search query string
• pageno (optional): Page number (default: 1)
• time_range (optional): Filter by time - "day", "month", or "year"
• language (optional): Language code (e.g., "en", "fr", "de", default: "all")
• safesearch (optional): Safe search level - "0", "1", or "2" (default: "0")

Example:

{
  "query": "Go programming best practices",
  "pageno": 1,
  "language": "en"
}

2. web_url_read

Reads and converts web page content to Markdown.

Parameters:

• url (required): URL to fetch
• startChar (optional): Starting character position
• maxLength (optional): Maximum characters to return
• section (optional): Extract specific heading section
• paragraphRange (optional): Paragraph range (e.g., "1-5", "10-")
• readHeadings (optional): Return only headings (boolean)

Example:

{
  "url": "https://example.com/article",
  "maxLength": 5000
}

Integration with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-searxng-go", "/app/mcp-searxng-go"],
      "env": {
        "SEARXNG_URL": "http://searxng:8080"
      }
    }
  }
}

Or if installed locally:

{
  "mcpServers": {
    "searxng": {
      "command": "/usr/local/bin/mcp-searxng-go",
      "env": {
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}

Configuration

Environment Variables

Variable	Required	Default	Description
SEARXNG_URL	✅ Yes	-	SearXNG instance URL (e.g., http://localhost:8080)
SEARXNG_SECRET	Recommended	-	Secret key for SearXNG instance
AUTH_USERNAME	No	-	Basic auth username for SearXNG
AUTH_PASSWORD	No	-	Basic auth password for SearXNG
HTTP_PROXY	No	-	HTTP proxy URL
HTTPS_PROXY	No	-	HTTPS proxy URL
CACHE_TTL	No	60	Cache time-to-live in seconds

SearXNG Configuration

The SearXNG instance is automatically configured to output JSON format. Custom search engines can be configured in searxng/config/settings.yml.

Available Make Commands

make help          # Show all available commands
make deps          # Download Go dependencies
make build         # Build the binary
make run           # Run locally (requires SEARXNG_URL)
make test          # Run tests
make docker-up     # Start Docker containers
make docker-down   # Stop Docker containers
make docker-logs   # View Docker logs
make install       # Install to /usr/local/bin
make build-all     # Build for multiple platforms

Architecture

┌─────────────────────────┐
│   AI Assistant (Claude) │
└───────────┬─────────────┘
            │ MCP Protocol (stdio)
            │
┌───────────▼─────────────┐
│    MCP Server (Go)      │
│  ┌──────────────────┐   │
│  │  Search Client   │───┼──► SearXNG (Docker)
│  │  URL Reader      │───┼──► Internet
│  │  Cache (60s TTL) │   │
│  └──────────────────┘   │
└─────────────────────────┘

Project Structure

mcp-searxng-claude-go/
├── main.go              # Application entry point
├── searxng.go          # SearXNG API client
├── urlreader.go        # URL fetching and HTML-to-Markdown conversion
├── cache.go            # In-memory caching with TTL
├── proxy.go            # HTTP proxy configuration
├── resources.go        # MCP resources (config, help)
├── Dockerfile          # Multi-stage Docker build
├── docker-compose.yml  # Service orchestration
├── Makefile            # Build automation
└── .env.example        # Environment template