mcp-searxng-claude-go by Tomlord1122 - MCP Server

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)

Clone the repository:

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

Create environment file:

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

Start services:

# Build and start both SearXNG and MCP server
docker compose up -d

# Or use convenience script
./start-mcp.sh

Verify it's running:
```
docker compose logs -f mcp-searxng-go
```

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

Install dependencies:
```
make deps
```
Build the binary:
```
make build
```

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