Quick Start · Features · Architecture · Comparison · Usage · MCP Tools · Client Config · Plugin · Contributing

🚀 Quick Start

docker run -d --name searxng-mcp --restart unless-stopped \
  -p 8888:8888 --memory=512m --cpus=1 \
  ghcr.io/whw23/searxng-http-mcp:latest

That's it. SearXNG + MCP server running on port 8888.

✨ Features

📦 Self-contained — SearXNG built into the Docker image
🔄 Dual transport — HTTP (Streamable HTTP) and stdio
🔐 Authentication — x-api-key + HTTP Basic Auth
🌐 Reverse proxy — SearXNG Web UI on the same port

📄 Multi-page fanout — up to 5 pages per call
⚡ Dynamic tool descriptions — live engine/category lists
🎯 Token-efficient — results trimmed to essentials
🧩 Claude Code Plugin — self-hosted marketplace

🏛 Architecture

graph LR
  Client([Client]) -->|:8888| Auth{Auth Middleware}
  Auth -->|/mcp| MCP[FastMCP Server]
  Auth -->|/*| Proxy[Reverse Proxy]
  MCP --> SearXNG[SearXNG :8080]
  Proxy --> SearXNG

  style Client fill:#4a90d9,color:#fff,stroke:#3a7bc8
  style Auth fill:#f5a623,color:#fff,stroke:#d4900e
  style MCP fill:#50c878,color:#fff,stroke:#3da85e
  style Proxy fill:#9b59b6,color:#fff,stroke:#8344a5
  style SearXNG fill:#e74c3c,color:#fff,stroke:#c0392b

📊 Comparison with Alternatives

Feature	✨ This project	mcp-searxng	searxng-mcp	searxng-deepdive	exa-mcp-server
Free & open source	✅	✅	✅	✅	❌ (paid API)
Zero-install Docker deploy	✅	❌	❌	❌	❌
Self-contained (built-in SearXNG)	✅	❌	❌	❌	N/A
Privacy (self-hosted)	✅	✅	✅	✅	❌
Authentication	✅	❌	❌	❌	✅
HTTP + stdio transport	✅	✅	✅	❌	❌
Multi-page fanout	✅	❌	❌	✅	❌
Dynamic tool descriptions	✅	❌	❌	✅	❌
Claude Code Plugin	✅	❌	❌	❌	❌
Web UI reverse proxy	✅	❌	❌	❌	❌
Language	Python	Node.js	Python	Node.js	TypeScript

📖 Usage

🌐 HTTP Mode (default)

# Without authentication
docker run -d --name searxng-mcp --restart unless-stopped \
  -p 8888:8888 --memory=512m --cpus=1 \
  ghcr.io/whw23/searxng-http-mcp:latest

# With authentication
docker run -d --name searxng-mcp --restart unless-stopped \
  -p 8888:8888 --memory=512m --cpus=1 \
  -e API_KEY=your-secret-key \
  ghcr.io/whw23/searxng-http-mcp:latest

🔗 MCP Endpoint	`http://localhost:8888/mcp/`
🖥 SearXNG Web UI	`http://localhost:8888/`

📡 stdio Mode

docker run --rm -i --memory=512m --cpus=1 \
  ghcr.io/whw23/searxng-http-mcp:latest --stdio

No ports exposed. Communication via stdin/stdout. SearXNG runs internally for the MCP tools.

⚙️ Environment Variables

Variable	Default	Description
`API_KEY`	(empty, no auth)	API key for authentication
`SEARXNG_URL`	`http://127.0.0.1:8080`	Internal SearXNG URL (rarely needs change)

🔐 Authentication

When API_KEY is set, all requests require one of:

x-api-key header — for MCP clients: x-api-key: your-key
HTTP Basic Auth — for browsers

[!TIP] Browser Login: When accessing the Web UI with API_KEY enabled, the browser will show a login dialog. Leave the username empty and enter your API key as the password.

When API_KEY is not set, all requests are open.

🔧 MCP Tools Reference

🔍 search — Search the web using SearXNG

Aggregates results from multiple search engines.

Parameter	Type	Required	Default	Description
`query`	str	yes	—	Search query string
`categories`	str	no	""	Comma-separated: general, images, videos, news, it, etc.
`language`	str	no	""	Language code (e.g., zh, en, ja)
`time_range`	str	no	""	day, month, year
`safesearch`	int	no	0	0=off, 1=moderate, 2=strict
`pageno`	int	no	1	Starting page number
`pages`	int	no	1	Number of pages to fetch (1-5)
`engines`	str	no	""	Comma-separated engine names (e.g., google,bing)

Returns: results, answers, suggestions, corrections, infoboxes.

💡 autocomplete — Get search query suggestions

Parameter	Type	Required	Description
`query`	str	yes	Query string to autocomplete

🔌 Client Configuration

Claude Desktop

Server mode — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "searxng": {
      "url": "http://your-server:8888/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}

Local mode:

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"]
    }
  }
}

Claude Code

Server mode:

claude mcp add searxng --transport http http://your-server:8888/mcp/ -- --header "x-api-key: your-secret-key"

Local mode:

claude mcp add searxng -- docker run --rm -i --memory=512m --cpus=1 ghcr.io/whw23/searxng-http-mcp:latest --stdio

Cursor

Server mode — add to Cursor MCP settings:

{
  "mcpServers": {
    "searxng": {
      "url": "http://your-server:8888/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}

Local mode:

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"]
    }
  }
}

VS Code Copilot

Server mode — add to .vscode/mcp.json:

{
  "servers": {
    "searxng": {
      "url": "http://your-server:8888/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}

Local mode:

{
  "servers": {
    "searxng": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"]
    }
  }
}

Windsurf

Server mode — add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "searxng": {
      "url": "http://your-server:8888/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}

Local mode:

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"]
    }
  }
}

Cline

Configure via Cline's MCP settings panel in VS Code (Cline > MCP Servers > Add).

Server mode:

{
  "mcpServers": {
    "searxng": {
      "url": "http://your-server:8888/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}

Local mode:

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"]
    }
  }
}

Continue.dev

Server mode — add to ~/.continue/config.yaml:

mcpServers:
  - name: searxng
    url: "http://your-server:8888/mcp/"
    headers:
      x-api-key: "your-secret-key"

Local mode:

mcpServers:
  - name: searxng
    command: docker
    args: ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"]

OpenCode

Server mode — edit .opencode.json:

{
  "mcpServers": {
    "searxng": {
      "type": "sse",
      "url": "http://your-server:8888/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}

Local mode:

{
  "mcpServers": {
    "searxng": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"]
    }
  }
}

Hermes Agent

Server mode — edit ~/.hermes/config.yaml:

mcp_servers:
  searxng:
    url: "http://your-server:8888/mcp/"
    headers:
      x-api-key: "your-secret-key"

Local mode:

mcp_servers:
  searxng:
    command: "docker"
    args: ["run", "--rm", "-i", "--memory=512m", "--cpus=1", "ghcr.io/whw23/searxng-http-mcp:latest", "--stdio"]

🧩 Claude Code Plugin

Add the marketplace, then install the plugin that fits your setup:

/plugin marketplace add whw23/searxng_http_mcp

	Local (Docker stdio)	Remote (HTTP)
Install	`/plugin install searxng-http-mcp@searxng-http-mcp`	`/plugin install searxng-http-mcp@searxng-http-mcp-remote`
How it works	Runs SearXNG in a local Docker container via stdio. Zero config.	Connects to a deployed SearXNG MCP server via HTTP.
Requires	Docker installed	Env vars: `SEARXNG_MCP_URL`, `SEARXNG_API_KEY`

Both plugins include the 🔍 /web-search-via-searxng skill for web search.

[!TIP] Remote mode setup: Add to ~/.claude/settings.json under the env field:
{
  "env": {
    "SEARXNG_MCP_URL": "http://your-server:8888/mcp/",
    "SEARXNG_API_KEY": "your-api-key"
  }
}
Then restart Claude Code.

🛠 SearXNG Configuration

🖥 Via Web UI

Access the SearXNG Web UI at http://localhost:8888/ to configure search engines, languages, and other settings. Changes persist during the container's lifetime.

💾 Via Volume Mount — persistent configuration

Mount the SearXNG config directory for persistent configuration:

docker run -d --name searxng-mcp --restart unless-stopped \
  -p 8888:8888 --memory=512m --cpus=1 \
  -v /path/to/searxng-config:/etc/searxng \
  ghcr.io/whw23/searxng-http-mcp:latest

SearXNG generates settings.yml on first startup. The container automatically enables JSON format output required by MCP tools.

🏗 Build from Source

git clone https://github.com/whw23/searxng_http_mcp.git
cd searxng-http-mcp
docker build -t searxng-http-mcp:local .
docker run -d --name searxng-mcp --restart unless-stopped \
  -p 8888:8888 --memory=512m --cpus=1 \
  searxng-http-mcp:local

🤝 Contributing

🍴 Fork the repository
🌿 Create a feature branch from dev
✍️ Make your changes
✅ Run tests: pytest tests/ -v
📬 Submit a PR to dev

Development happens on the dev branch. Merges to main trigger image builds.

📄 License

MIT — MCP server code.

SearXNG itself is licensed under AGPL-3.0-or-later.

SearXNG HTTP MCP

🚀 Quick Start

✨ Features

🏛 Architecture

📊 Comparison with Alternatives

📖 Usage

🌐 HTTP Mode (default)

📡 stdio Mode

⚙️ Environment Variables

🔐 Authentication

🔧 MCP Tools Reference

🔌 Client Configuration

🧩 Claude Code Plugin

🛠 SearXNG Configuration

🏗 Build from Source

🤝 Contributing

📄 License

Reviews