mcp-searxng

The SearXNG MCP Server integrates the SearXNG web search API into the MCP (Model Context Protocol) framework, enabling structured web search capabilities within MCP clients. It exposes two primary tools: searxng_web_search for performing general and filtered web searches with pagination, time range, language, and safe search controls; and web_url_read which fetches and converts content from a URL into markdown with options for content extraction such as section targeting, character limits, and heading-based extraction. The server reads configuration from environment variables (notably SEARXNG_URL) and forwards queries to the configured SearXNG instance, returning search results in MCP-compatible payloads. This setup allows applications to perform browseable web searches, news and article retrieval, and URL content extraction via a consistent MCP interface.

Prerequisites:

• Node.js (recommended latest LTS) and npm installed on your system
• Access to a SearXNG instance (SEARXNG_URL) or a proxy chain if required

Install options:

1. NPX-based (recommended for testing or ephemeral setups):

• Ensure you have npm installed
• Run the MCP server directly via npx (no permanent install needed):

# Run the MCP server using NPX (will install temporarily if not cached)
npx -y mcp-searxng

• Configure the required environment variable when running or via MCP config (see mcp_config):

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

2. Global/NPM install (persistent server):

• Install the package globally so you can run it as a command:

npm install -g mcp-searxng

• Then configure the MCP server to run the installed CLI and provide SEARXNG_URL:

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

3. Docker (alternative):

• Pull and run the pre-built image, then point SEARXNG_URL via env:

docker pull isokoliuk/mcp-searxng:latest

• And in MCP config:

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "isokoliuk/mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Note: The exact command options may vary by deployment style (NPX, npm, Docker). Use the approach that matches your environment and set SEARXNG_URL to your SearXNG instance.

Tips and common considerations:

• Always set SEARXNG_URL to your SearXNG endpoint. If your SearXNG instance requires authentication, you can pass AUTH_USERNAME and AUTH_PASSWORD in the MCP config env as needed.
• You can add optional variables such as USER_AGENT, HTTP_PROXY, HTTPS_PROXY, and NO_PROXY to adapt network routing and identity when accessing the SearXNG API.
• The HTTP transport (MCP_HTTP_PORT) is optional and enables REST-like MCP interactions over HTTP. If using HTTP transport, ensure the port is exposed and not blocked by firewalls.
• For local testing, starting with NPX is convenient. For production, consider a persistent deployment (Docker, systemd service, or container orchestration) and securely manage credentials.
• The README supports both the NPX and Docker deployment patterns; you can mix and match environment variables as needed. Ensure your MCP client uses the correct server name (e.g., searxng) and that SEARXNG_URL is reachable from the MCP host.