Overview

The SearXNG MCP Server implements the Model Context Protocol (MCP) as a companion service for SearXNG. It provides a secure, scalable API that manages context for large-language and other contextual models so search engines (like SearXNG) can integrate models without directly handling model sessions, state, or sensitive context exchange. By separating context management into a dedicated service, developers can reuse model-aware logic across multiple search instances and control lifecycle, caching, and access control in one place.

This server is useful when you want to enhance search results with model-driven features — for example query expansion, contextual reranking, or conversational threads — while keeping model interactions auditable and isolated. It supports session management, context storage, and a lightweight auth layer so SearXNG (or other tools) can securely request context-aware model operations.

Features

Lightweight MCP-compatible context server for integration with SearXNG
Session and context lifecycle management (create, update, expire)
Token-based authentication support for secure API calls
Docker-friendly deployment with simple configuration via environment variables
Designed for integration into search pipelines: reranking, enrichment, personalization
Logging and basic health endpoint for monitoring and orchestration

Installation / Configuration

Clone the project and run with Docker Compose

git clone https://github.com/ihor-sokoliuk/mcp-searxng.git
cd mcp-searxng
docker-compose up -d

Basic Docker run example (adjust image name/tag if needed):

docker run -d \
  --name mcp-searxng \
  -p 3000:3000 \
  -e MCP_PORT=3000 \
  -e MCP_AUTH_TOKEN="replace-with-secret" \
  ihor-sokoliuk/mcp-searxng:latest

Example docker-compose.yml (minimal)

version: "3.8"
services:
  mcp:
    image: ihor-sokoliuk/mcp-searxng:latest
    ports:
      - "3000:3000"
    environment:
      - MCP_PORT=3000
      - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN:-changeme}
    restart: unless-stopped

Environment variables (common)

Variable	Default	Description
MCP_PORT	3000	Port the server listens on
MCP_AUTH_TOKEN	(none)	Shared token for simple auth between SearXNG and MCP server
MCP_SESSION_TTL	3600	Default session lifetime in seconds
LOG_LEVEL	info	Server logging verbosity

After deploying, set your secret token as an environment variable and configure SearXNG (or other clients) to call the MCP server URL with that token.

SearXNG configuration snippet (example)

# searxng/settings.yml (example placeholder)
mcp:
  url: "http://mcp-server.local:3000"
  auth_token: "replace-with-secret"
  timeout: 5

API calls from SearXNG should include the bearer token header:

Authorization: Bearer <MCP_AUTH_TOKEN>

Available Resources

The server exposes a small set of resources useful for model-context workflows (names are illustrative — check your deployment’s /openapi or docs endpoint for exact routes):

Health: simple endpoint to check readiness and uptime
Sessions: create, retrieve, extend, and delete model sessions
Contexts: attach, read, and expire contextual data tied to sessions
Actions / Forwarding: endpoints to forward model inputs or requests to a configured model executor (if enabled)
Metrics / Logs: basic logs and metrics endpoints for monitoring

Example health check (curl)

curl -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  http://localhost:3000/health

Create a session (illustrative)

curl -X POST http://localhost:3000/sessions \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"alice","ttl":3600}'

Fetch or update context for a session similarly via /sessions/{id}/context.

Use Cases

Contextual Reranking: When SearXNG returns a list of results, send the query plus candidate snippets to the MCP server. The MCP server maintains a session and can call a model to score or rerank candidates using stored user/session context.
Conversational Search: Keep conversation history in MCP sessions so subsequent queries are interpreted with prior turns, enabling follow-up question resolution without exposing conversation storage to the search backend.
Query Enrichment: Use MCP-managed context to expand or rewrite user queries using model prompts, then pass enriched queries back to SearXNG for retrieval.
Privacy & Isolation: Store sensitive context (user tokens, preferences) inside the MCP service and only expose derived prompts/inputs to the model runtime. The MCP server acts as a control point for access and auditing.
Multi-instance Scaling: Run one or more MCP servers behind a load balancer; SearXNG instances can point to the same MCP cluster to share session continuity across frontends.

Next Steps

Review the server’s OpenAPI or documentation endpoint after deployment to see concrete routes and schemas.
Integrate MCP calls into SearXNG request flow (pre- or post-processing hooks) to add context-aware behavior.
Add secure secrets management (Vault, Kubernetes Secrets) for production tokens and consider mTLS or OAuth for stronger authentication if required.

SearXNG MCP Server for Contextual Models