Skip to main content
Glama
whw23

searxng-http-mcp

by whw23
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

A self-contained MCP server that wraps SearXNG — a free, privacy-respecting metasearch engine that aggregates results from 200+ search engines.

🚀 Quick Start

Server mode — deploy once, connect from any client:

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

Then connect your client to http://YOUR_HOST:YOUR_PORT/mcp/. To enable API key auth, see Authentication.

Local mode — no server needed, run directly in your client:

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

Add this as a stdio MCP server in your client — see Client Configuration for details.

uvx mode — if you already have SearXNG running (install guide):

uvx searxng-http-mcp

Set SEARXNG_URL to point to your SearXNG instance (default: http://127.0.0.1:8080).

Related MCP server: @caikiji/mcp-search

✨ Features

Search

  • 🔍 200+ search engines — Google, Bing, DuckDuckGo, Brave, and more via SearXNG

  • 📂 30+ categories — news, images, videos, science, IT, and more

  • 📄 Multi-page fanout — up to 5 pages per call

  • 💡 Autocomplete suggestions — discover relevant search terms

  • 🗂 Engine discovery — query available engines grouped by category

  • 🎯 Token-efficient — results trimmed to essentials

Infrastructure

  • 📦 Self-contained — SearXNG built into Docker image

  • 🔄 Triple transport — HTTP server, Docker stdio, and uvx standalone

  • 🔐 Authentication — x-api-key + HTTP Basic Auth

  • 🌐 Reverse proxy — SearXNG Web UI on the same port

  • ⚡ Dynamic tool descriptions — live category lists injected at startup

  • 📐 Rich JSON Schema — enum constraints, range limits, and descriptions on every parameter

🏛 Architecture

graph LR
  Client(["client:YOUR_PORT"]) --> Expose(":8888")

  subgraph Container["🐳 Docker Container"]
    direction LR
    Expose --> Auth{Auth}
    Auth -->|/mcp| MCP[FastMCP Server]
    Auth -->|/*| Proxy[Reverse Proxy]
    MCP --> SearXNG[SearXNG :8080]
    Proxy --> SearXNG
  end

  style Expose fill:none,stroke:#2496ed,stroke-dasharray:5 5,color:#2496ed

  style Client fill:#4a90d9,color:#fff,stroke:#3a7bc8
  style Container fill:#f0f4f8,stroke:#2496ed,stroke-width:2px,color:#2496ed
  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

There are 20+ SearXNG MCP servers and many more general-purpose search MCPs. Most SearXNG wrappers only expose a basic search tool, leaving SearXNG's categories, autocomplete, and engine metadata unused. We picked five alternatives that each represent a distinct category:

  • 88plug/searxng-mcp — richest tool surface among SearXNG MCPs (7 tools: rendered fetch, research mode, parallel queries)

  • ihor/mcp-searxng — most GitHub stars among SearXNG MCPs

  • open-webSearch — top free multi-engine alternative outside the SearXNG ecosystem (Bing, Baidu, DuckDuckGo, Brave, etc.)

  • exa-mcp-server — most popular commercial search API MCP

  • Perplexity MCP — commercial AI-powered search, highest star count in the search MCP space

MCP is designed for composition — clients connect multiple specialized servers, each doing one thing well. Some alternatives bundle URL fetching, rendered page extraction, multi-query fan-out, or research modes into the search server. We keep the tool surface to three (search, autocomplete, engine discovery) by design:

  • URL fetching is a separate concern. MCP clients already ship dedicated tools (WebFetch, Playwright MCP, Jina Reader). Bundling fetch into a search server mixes responsibilities and duplicates the client ecosystem.

  • Multi-query parallel search is client-side orchestration. LLM clients can fire multiple search calls in parallel — a search_many tool only adds token overhead for tool selection with no real benefit.

  • Research / synthesis belongs in the LLM layer. The model is the best synthesizer. Pushing multi-step research logic into the MCP server couples application concerns to infrastructure.

Instead we invest in what the alternatives above lack: complete SearXNG API coverage (categories, autocomplete, engine metadata — capabilities most wrappers leave on the table), self-contained deployment, authentication, Web UI reverse proxy, and AI coding agent plugin integration (Claude Code / Copilot CLI / Codex CLI).

📖 Usage

🌐 HTTP Mode (default)

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

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

📡 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.

🐍 uvx Mode

# Connect to a local SearXNG instance (default: http://127.0.0.1:8080)
uvx searxng-http-mcp

# Connect to a remote SearXNG instance
SEARXNG_URL=http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT uvx searxng-http-mcp

Requires Python 3.14+ and an existing SearXNG instance. No Docker needed.

⚙️ Environment Variables

🔐 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

Aggregates results from 200+ search engines with privacy.

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

No parameters. Returns the list of enabled engines grouped by category.

Returns:

{
  "categories": ["general", "images", "videos", "news", ...],
  "engines": ["google", "bing", "duckduckgo", ...],
  "category_engines": {
    "general": ["google", "bing", "duckduckgo", "brave", ...],
    "science": ["arxiv", "google scholar", "pubmed", ...],
    ...
  }
}

Use this to discover what engines are available before calling search with specific engines or categories filters.

🔌 Client Configuration

The following is a baseline server-mode (remote HTTP) example using the standard mcpServers JSON structure. Many clients accept this structure, but field names and required type values differ — see the NOTE below and adjust for your client:

{
  "mcpServers": {
    "searxng": {
      "type": "http",
      "url": "http://YOUR_HOST:YOUR_PORT/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}
NOTE

Field-name differences:ZCode uses mcp.servers; Kilo Code uses a top-level mcp key with "type": "remote"; Windsurf uses serverUrl instead of url; VS Code Copilot uses a top-level servers key; OpenCode nests under mcp with "type": "remote"; Codex and Hermes use mcp_servers (TOML/YAML). For Claude Code, "type": "http" is required — without it the entry is read as a stdio server and skipped. For Cline, set "type": "streamableHttp" on remote HTTP servers.

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

{
  "mcpServers": {
    "searxng": {
      "url": "http://YOUR_HOST:YOUR_PORT/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"]
    }
  }
}

uvx mode:

{
  "mcpServers": {
    "searxng": {
      "command": "uvx",
      "args": ["searxng-http-mcp"],
      "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" }
    }
  }
}

Server mode (CLI):

claude mcp add --transport http searxng http://YOUR_HOST:YOUR_PORT/mcp/ \
  --header "x-api-key: your-secret-key"

Server mode (JSON) — the same mcpServers structure works in a team-shared project .mcp.json or a user-wide global ~/.claude.json:

{
  "mcpServers": {
    "searxng": {
      "type": "http",
      "url": "http://YOUR_HOST:YOUR_PORT/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}

Local mode:

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

uvx mode:

claude mcp add --transport stdio searxng -- uvx searxng-http-mcp

Server mode — add to ~/.codex/config.toml:

[mcp_servers.searxng]
url = "http://YOUR_HOST:YOUR_PORT/mcp/"
http_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"]

uvx mode:

[mcp_servers.searxng]
command = "uvx"
args = ["searxng-http-mcp"]

Server mode — edit .cursor/mcp.json:

{
  "mcpServers": {
    "searxng": {
      "url": "http://YOUR_HOST:YOUR_PORT/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"]
    }
  }
}

uvx mode:

{
  "mcpServers": {
    "searxng": {
      "command": "uvx",
      "args": ["searxng-http-mcp"],
      "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" }
    }
  }
}

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

{
  "servers": {
    "searxng": {
      "type": "http",
      "url": "http://YOUR_HOST:YOUR_PORT/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}

Local mode:

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

uvx mode:

{
  "servers": {
    "searxng": {
      "type": "stdio",
      "command": "uvx",
      "args": ["searxng-http-mcp"],
      "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" }
    }
  }
}

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

{
  "mcpServers": {
    "searxng": {
      "serverUrl": "http://YOUR_HOST:YOUR_PORT/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"]
    }
  }
}

uvx mode:

{
  "mcpServers": {
    "searxng": {
      "command": "uvx",
      "args": ["searxng-http-mcp"],
      "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" }
    }
  }
}

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

Server mode:

{
  "mcpServers": {
    "searxng": {
      "type": "streamableHttp",
      "url": "http://YOUR_HOST:YOUR_PORT/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"]
    }
  }
}

uvx mode:

{
  "mcpServers": {
    "searxng": {
      "command": "uvx",
      "args": ["searxng-http-mcp"],
      "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" }
    }
  }
}

Server mode — edit opencode.json:

{
  "mcp": {
    "searxng": {
      "type": "remote",
      "url": "http://YOUR_HOST:YOUR_PORT/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      }
    }
  }
}

Local mode:

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

uvx mode:

{
  "mcp": {
    "searxng": {
      "type": "local",
      "command": ["uvx", "searxng-http-mcp"]
    }
  }
}

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

mcp_servers:
  searxng:
    url: "http://YOUR_HOST:YOUR_PORT/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"]

uvx mode:

mcp_servers:
  searxng:
    command: "uvx"
    args: ["searxng-http-mcp"]

Server mode — edit ~/.zcode/cli/config.json (user-wide) or .zcode/config.json (project):

{
  "mcp": {
    "servers": {
      "searxng": {
        "type": "http",
        "url": "http://YOUR_HOST:YOUR_PORT/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"]
      }
    }
  }
}

uvx mode:

{
  "mcp": {
    "servers": {
      "searxng": {
        "command": "uvx",
        "args": ["searxng-http-mcp"],
        "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" }
      }
    }
  }
}

ZCode also accepts the standard mcpServers structure (e.g. in .agents/mcp.json). Alternatively, add servers via Settings → MCP Servers → New MCP Server.

Server mode — edit ~/.config/kilo/kilo.jsonc (global) or .kilo/kilo.jsonc (project):

{
  "mcp": {
    "searxng": {
      "type": "remote",
      "url": "http://YOUR_HOST:YOUR_PORT/mcp/",
      "headers": {
        "x-api-key": "your-secret-key"
      },
      "enabled": true
    }
  }
}

Local mode:

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

uvx mode:

{
  "mcp": {
    "searxng": {
      "type": "local",
      "command": ["uvx", "searxng-http-mcp"],
      "environment": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" },
      "enabled": true
    }
  }
}

Install the MCP adapter once, then add a standard mcpServers block — e.g. in ~/.pi/agent/mcp.json (all projects) or .pi/mcp.json (project):

pi install npm:pi-mcp-adapter

Restart Pi after installing.

Server mode:

{
  "mcpServers": {
    "searxng": {
      "url": "http://YOUR_HOST:YOUR_PORT/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"]
    }
  }
}

uvx mode:

{
  "mcpServers": {
    "searxng": {
      "command": "uvx",
      "args": ["searxng-http-mcp"],
      "env": { "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT" }
    }
  }
}

🧩 AI Coding Agent Plugin

Compatible with Claude Code, GitHub Copilot CLI, and OpenAI Codex CLI. Add the marketplace, then install the plugin that fits your setup:

/plugin marketplace add whw23/searxng_http_mcp

All plugins include:

  • 🔍 /web-search-via-searxng skill — search the web with category selection guide and usage rules

  • 🤖 web-searcher agent — research subagent with:

    • 🌐 Multi-language parallel search — auto-detects query language, searches in multiple languages for broader coverage

    • 🛡 Source credibility tiers — Tier 1/2/3 classification with AI poisoning defense

    • ✅ Cross-validation — key facts require 2+ independent sources

    • 🔍 WebFetch deep reading — reads full pages from credible sources, not just snippets

    • 🔄 Multi-round iterative search — up to 3 rounds with automatic deepening on gaps

    • ⏱ Timeliness evaluation — flags outdated content, states source date ranges

    • 📝 Footnote-style references — structured output with inline source citations

/plugin install searxng-http-mcp-standalone@searxng-http-mcp

Runs via uvx. Requires Python 3.14+ and an existing SearXNG instance. Set SEARXNG_URL in ~/.claude/settings.json:

{
  "env": {
    "SEARXNG_URL": "http://YOUR_SEARXNG_HOST:YOUR_SEARXNG_PORT"
  }
}
/plugin install searxng-http-mcp@searxng-http-mcp

Runs SearXNG in a local Docker container via stdio. Requires Docker installed.

/plugin install searxng-http-mcp-remote@searxng-http-mcp

Connects to a deployed SearXNG MCP server. Requires env vars SEARXNG_MCP_URL and SEARXNG_API_KEY.

Add to ~/.claude/settings.json under the env field:

{
  "env": {
    "SEARXNG_MCP_URL": "http://YOUR_HOST:YOUR_PORT/mcp/",
    "SEARXNG_API_KEY": "your-api-key"
  }
}

Then restart Claude Code.

🛠 SearXNG Configuration

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

Mount the SearXNG config directory for persistent configuration:

docker run -d --name searxng-mcp --restart unless-stopped \
  -p YOUR_PORT: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 YOUR_PORT:8888 --memory=512m --cpus=1 \
  searxng-http-mcp:local

🤝 Contributing

See CONTRIBUTING.md for the full workflow, CI requirements, and development setup.

  1. 🍴 Fork the repository and enable GitHub Actions in your fork

  2. 🌿 Create a feature branch from dev

  3. ✍️ Make your changes

  4. ✅ Run tests: pytest tests/ -v — CI must pass in your fork before opening a PR

  5. 📬 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.

Available Tools

3 tools
autocompleteA
Read-onlyIdempotent

Get search query suggestions from SearXNG.

Returns a list of autocomplete suggestions for the given partial query. Use this to discover relevant search terms before performing a full search.

Best results come from 1-2 meaningful keywords (e.g., "python async"). Single characters return overly broad suggestions; full sentences return none.

Makes an external API call to the configured autocomplete backend (e.g., Bing, Google). Not suitable for full web search (use search tool) or engine discovery (use engine_info tool).

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesPartial query string to get suggestions for. Best results with 1-2 keywords (e.g., 'python async'). Single characters are too broad; full sentences return nothing.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses that it 'Makes an external API call to the configured autocomplete backend (e.g., Bing, Google)', and explains behavioral nuances like single characters returning broad suggestions and sentences returning none. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence earns its place: purpose, usage, parameter tips, and behavioral note. It is front-loaded with the primary action and stays succinct without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with rich annotations and an output schema, the description fully covers purpose, usage, exclusions, parameter behavior, and external side effects. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the query parameter (100% coverage), but the description adds critical semantic guidance: 'Best results come from 1-2 meaningful keywords', 'Single characters return overly broad suggestions; full sentences return none' – meaningfully enriching parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Get search query suggestions from SearXNG', using a specific verb and resource. It clearly distinguishes from siblings by stating it is not for full web search (use search tool) or engine discovery (use engine_info tool).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use ('Use this to discover relevant search terms before performing a full search'), provides query-format guidance (1-2 keywords, avoid single chars/full sentences), and names alternatives (search, engine_info) with exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

engine_infoA
Read-onlyIdempotent

Get available search engines and categories from the SearXNG instance.

Returns the list of enabled engines grouped by category. Use this to discover what engines and categories are available before calling search with specific engines or categories filters.

Response is cached for 5 minutes. Does not perform any web search — use the search tool for that.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds valuable behavioral context: 'Response is cached for 5 minutes. Does not perform any web search.' This goes beyond the annotations and clarifies the tool's side-effect-free, cacheable behavior and its non-search nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, opening with the primary purpose, followed by the return format, usage guidance, and a clarifying note about caching and non-search behavior. Every sentence contributes meaning without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given this is a simple, parameterless tool with an output schema, the description covers all necessary aspects: purpose, return shape, usage timing, caching, and exclusions. It fully prepares the agent to decide when and how to invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema provides full coverage. The description appropriately focuses on the returned data structure ('list of enabled engines grouped by category') rather than parameters. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Get available search engines and categories from the SearXNG instance.' It specifies the resource and the nature of the output. It also distinguishes itself from sibling tools by explicitly noting it 'Does not perform any web search — use the search tool for that.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: 'Use this to discover what engines and categories are available before calling search with specific engines or categories filters.' This clearly indicates when to use the tool versus the search tool, making usage context unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.1.3
    • Changedautocomplete1 field changed
      • changedInput schema / properties / query / description
        Previous value: -"Partial query string to get suggestions for"New value: +"Partial query string to get suggestions for. Best results with 1-2 keywords (e.g., 'python async'). Single characters are too broad; full sentences return nothing."
  2. 1 tool updatev1.1.2
    • Changedsearch7 fields changed
      • changedInput schema / properties / categories / description
        Previous value: -"Comma-separated category names to focus on (e.g., 'general,news,science')"New value: +"Comma-separated category names to focus on (e.g., 'general,news,science'). Prefer this over 'engines' to narrow results — categories leverage multiple engines automatically. Call engine_info to discover available categories."
      • changedInput schema / properties / engines / description
        Previous value: -"Comma-separated engine names to use (e.g., 'google,arxiv,wikipedia')"New value: +"Comma-separated engine names to use (e.g., 'google,arxiv,wikipedia'). Only use when you need a specific source; otherwise prefer 'categories'. Overrides category-based engine selection when set."
      • changedInput schema / properties / language / description
        Previous value: -"Search language code (e.g., 'en', 'zh', 'ja', 'de')"New value: +"Search language code (e.g., 'en', 'zh', 'ja', 'de'). Filters results to the specified language. Omit to search all languages."
      • changedInput schema / properties / max_results / description
        Previous value: -"Maximum number of results to return"New value: +"Maximum number of results to return. Applied after aggregation across pages."
      • changedInput schema / properties / pageno / description
        Previous value: -"Starting page number"New value: +"Starting page number. Use with 'pages' for pagination."
      • changedInput schema / properties / pages / description
        Previous value: -"Number of pages to fetch in parallel (multi-page fanout)"New value: +"Number of pages to fetch in parallel (multi-page fanout). Higher values return more results but increase latency. Use 2-3 for comprehensive research."
      • changedInput schema / properties / time_range / description
        Previous value: -"Restrict results to those published within this time window"New value: +"Restrict results to those published within this time window. Omit for no time restriction."
  3. 3 tool updatesv1.1.0
    • Addedautocomplete
    • Addedengine_info
    • Addedsearch
  4. 3 tool updatesv0.1.1
    • Removedautocomplete
    • Removedengine_info
    • Removedsearch
  5. 3 tool updatesv0.1.0
    • First observedautocomplete
    • First observedengine_info
    • First observedsearch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.9/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: search performs web searches, autocomplete provides query suggestions, and engine_info lists available engines/categories. The descriptions explicitly state which tool to use for which task, eliminating any ambiguity.

Naming Consistency5/5

All tool names are lowercase and use underscores for compound names (engine_info), maintaining a consistent and predictable naming style. Though not following a strict verb_noun pattern, the convention is uniform and easy to learn.

Tool Count5/5

Three tools is a well-scoped count for this server's purpose. Each tool serves a distinct and necessary function for a search metasearch service, and none feel redundant or missing.

Completeness5/5

The tool set covers the essential search lifecycle: performing searches, getting autocomplete suggestions, and discovering engine/category options. No obvious gaps exist for the stated purpose of providing a SearXNG interface.

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • searxng-mcp

    88plug
    F
    license
    A
    quality
    A
    maintenance
    An MCP server for SearXNG that provides web search capabilities with concise model-visible output while preserving full result payloads in metadata. It supports search, parallel fetching, URL extraction, and research workflows through both local stdio and streamable HTTP transports.
    7
    2
    -

  • @caikiji/mcp-search

    caikiji
    A
    license
    Not graded
    quality
    D
    maintenance
    Privacy-respecting, self-hosted metasearch MCP server that aggregates results from multiple search engines and fetches page content as Markdown.
    41 npm
    1
    MIT

  • MCP Server SearXNG

    jhstatewide
    A
    license
    A
    quality
    B
    maintenance
    MCP server for SearXNG meta search engine with enhanced error handling and parameter validation for AI agents. Enables privacy-focused web searches with structured JSON results and advanced filtering.
    1
    100 npm
    2
    MIT

  • searxng-mcp

    Jian-Zhan
    F
    license
    Not graded
    quality
    D
    maintenance
    Privacy-focused web search MCP server using SearXNG with Streamable HTTP transport, supporting authentication and advanced search parameters.
    -

Appeared in Searches