This MCP server exposes a SearXNG-backed web search tool.
Search the web using a required query.
Control the number of results with max_results (default 10).
Request a specific results page with page (default 1).
Filter searches by categories, language, and time_range (day, month, or year).
Return results from the configured SearXNG instance.
Provides search capabilities through a SearXNG instance, allowing clients to run web searches and retrieve results as JSON.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@searxng-mcp-server search for fastmcp python and show me the top 5 results"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A simple MCP Server for the SearXNG hosted search service.
uv sync
cp .env.example .envRelated MCP server: agent-tools
# Local (STDIO)
uv run searxng-mcp
# Remote (HTTP) — serves at http://127.0.0.1:8000/mcp
MCP_TRANSPORT=http uv run searxng-mcpSettings are read from .env (see .env.example). Real environment variables take precedence.
Only .env is loaded — .env.example is just a template. Set SEARXNG_URL to your SearXNG instance, which must have the JSON format enabled in its settings.yml:
search:
formats: [html, json]Install the searxng-mcp command, then register it with Claude Code:
just install # or: uv build && uv tool install --reinstall dist/searxng_mcp-*.whl
claude mcp add SearXNG -s user -e SEARXNG_URL=https://searx.example.com -- searxng-mcp-s user makes it available in every project; leave it off to add it to the current project only. Start a new Claude Code session to load the tools, which appear as mcp__SearXNG__search and mcp__SearXNG__fetch.
The installed command doesn't read this repo's .env, so pass settings with -e. Add one -e per setting, for example -e SEARXNG_SAFESEARCH=0. Without SEARXNG_URL, searches fail with Request to SearXNG at http://localhost:8080 failed.
To run from a checkout instead of installing (using its .env):
claude mcp add SearXNG -- uv run --directory /path/to/searxng-mcp-server searxng-mcpCheck the server with claude mcp get SearXNG, and remove it with claude mcp remove SearXNG -s user.
If the server is already running somewhere in HTTP mode (for example, with Docker), point Claude Code at its URL instead of installing it locally:
claude mcp add --transport http SearXNG -s user https://mcp.example.com/mcpThe URL must end in /mcp. Settings such as SEARXNG_URL belong to the remote server, so there are no -e flags here.
If the server is behind a reverse proxy that requires a token, add the header the proxy expects:
claude mcp add --transport http SearXNG -s user https://mcp.example.com/mcp \
--header "Authorization: Bearer <token>"The header is saved in plain text in ~/.claude.json (or .mcp.json with -s project, so don't commit a token that way).
searchSearches the web through your SearXNG instance. Takes a query plus optional max_results (default 10), categories, language, time_range (day, month, or year), and page. Returns each result's title, URL, snippet, and engine, along with any answers and suggestions.
fetchFetches a web page and returns its main content as Markdown, with menus, footers, and ads stripped out. Takes a url and an optional max_length (default 20000 characters). Returns the final URL after redirects, the page title, the content, and whether it was truncated. Plain-text and JSON responses are returned as-is; other content types, such as images, are rejected.
Settings:
Variable | Default | Purpose |
|
| Request timeout, in seconds |
|
| Largest download allowed |
|
| Allow |
By default, fetch refuses URLs that resolve to localhost, private network, or link-local addresses, and checks every redirect. This stops anyone who can reach the server from using it to probe your internal network. Only set FETCH_ALLOW_PRIVATE=true when running over STDIO or on a trusted network. The check doesn't defend against DNS rebinding, so it's not a substitute for authentication on a public endpoint.
The clients/ directory has bash scripts for talking to the server over HTTP. They require curl and jq, and the server must be running in HTTP mode:
MCP_TRANSPORT=http uv run searxng-mcpThe scripts connect to http://127.0.0.1:8000/mcp by default. Set MCP_URL to point them at another server.
./clients/list-tools.sh
./clients/list-tools.sh http://myhost:8000/mcp # or pass the URL directlyPrints each tool's name, description, and input schema.
./clients/search.sh "fastmcp python" # 5 results by default
./clients/search.sh "fastmcp python" 10 # choose how many
MCP_URL=http://myhost:8000/mcp ./clients/search.sh "fastmcp python"Prints the results as JSON. If the search fails (for example, SearXNG is unreachable), the error goes to stderr and the script exits with status 1.
./clients/fetch.sh https://example.com # up to 20000 characters
./clients/fetch.sh https://example.com 5000 # choose the limit
./clients/fetch.sh https://example.com > page.md # save just the contentPrints the page content as Markdown to stdout, and the title and final URL to stderr, so redirecting stdout saves only the content. Errors (for example, a blocked private address) go to stderr and the script exits with status 1.
The simplest way is Docker Compose, which reads settings from .env and serves HTTP on 127.0.0.1:8000:
docker compose up -d --buildCompose always runs the container in HTTP mode, even if your .env sets MCP_TRANSPORT=stdio for local use.
To run the image without Compose, pass your settings and override the transport settings yourself:
docker build -t searxng-mcp .
docker run -d -p 127.0.0.1:8000:8000 --env-file .env \
-e MCP_TRANSPORT=http -e MCP_HOST=0.0.0.0 -e MCP_PORT=8000 searxng-mcp.env is excluded from the image, so settings are never baked in.
The HTTP endpoint has no authentication, which is why the port is bound to localhost. Don't expose it publicly without a protected reverse proxy in front of it.
Search the web using SearXNG.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Results page number, starting at 1. | |
| query | Yes | The search query. | |
| language | No | Language code, e.g. "en" or "en-US". Defaults to SEARXNG_LANGUAGE. | |
| categories | No | Comma-separated SearXNG categories, e.g. "general", "news", "it". | |
| time_range | No | Only return results from the last day, month, or year. | |
| max_results | No | Maximum number of results to return. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: not whether the call is read-only (implied but unstated), not whether SearXNG rate-limits or fails on some categories, not how pagination interacts with max_results. The presence of an output schema excuses explaining return values, but the operational behavior remains undocumented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler; the verb and resource lead. It is efficient, but the brevity reflects under-specification as much as discipline, so it does not reach 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter search tool with no annotations, the description should convey freshness/pagination behavior and any constraints on result quality. The output schema removes the need to describe return shape, but the tool's operational contract is left entirely to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters (query, page, language, categories, time_range, max_results) are already documented in the schema, including the SEARXNG_LANGUAGE default and enum values for time_range. The description adds nothing beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb ('Search') and resource ('the web') and identifies the backend as SearXNG, so the agent knows exactly what capability this is. With no sibling tools there is nothing to differentiate against, but the description stops short of stating scope (e.g., whether it aggregates engines, returns snippets, or respects freshness).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus other options, nor any hint about when to set categories, time_range, or language to narrow results. With no siblings the alternative-routing burden is absent, but a user still gets no situational guidance at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0searchScored across 1 tool
There is only one tool, so there is no possibility of selecting the wrong one. Its purpose is stated clearly and unambiguously.
The single tool uses a clear, conventional verb name ('search') in snake_case, but with only one tool there is no pattern to demonstrate consistency across actions or resources.
A one-tool surface is thin even for a search-focused server; capabilities like fetching page content or querying instance configuration have no entry point. It is defensible for a minimal wrapper but leaves the server under-scoped.
Web search is covered, but the SearXNG domain typically includes parameters like category, language, time range, and pagination, plus follow-up needs such as retrieving a result page or listing available engines/instances. None of these secondary operations are exposed, creating potential dead ends.
Search Bluesky posts and feeds; read profiles, threads, and trends. STDIO or Streamable HTTP.
Unified 15-tool SEO, SERP, clean Markdown & GEO (LLM citation Share-of-Voice) MCP server.
Search and run data, text, code, PDF and web APIs. Requests not stored. Network tools need a key.
Search, inspect and invoke every public tool on Invokera through one MCP connection.
