SearXNG MCP Server

An MCP server that integrates the SearXNG API, giving AI assistants web search and URL reading capabilities.

Quick Start

Requires Bun.

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "searxng": {
      "command": "bunx",
      "args": ["@tterrasson/mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Replace YOUR_SEARXNG_INSTANCE_URL with the URL of your SearXNG instance, for example https://search.example.com.

Features

• Web Search: General queries, news, articles, with pagination.
• URL Content Reading: Content extraction powered by Readability (Firefox Reader Mode). Strips navigation, ads, and boilerplate before converting to Markdown, with pagination, section filtering, and heading extraction.
• Pagination: Control which page of results to retrieve.
• Time Filtering: Filter results by time range: day, month, or year.
• Language Selection: Filter results by preferred language.
• Safe Search: Control the search result filtering level.
• Category Filtering: Restrict results to specific engine types (news, images, science, etc.).

How It Works

mcp-searxng is a standalone MCP server that runs with Bun. Your AI assistant connects to it through the MCP protocol, and the server queries any SearXNG instance through its HTTP JSON API.

Not a SearXNG plugin: This project cannot be installed as a native SearXNG plugin. Point it at an existing SearXNG instance by setting SEARXNG_URL.

AI Assistant
        |  MCP protocol
        v
  mcp-searxng  (this project, Bun process)
        |  HTTP JSON API (SEARXNG_URL)
        v
  SearXNG instance

Tools

web_search

Execute web searches with pagination.

Inputs:

• query (string): The search query. This string is passed to external search services.
• pageno (number, optional): Search page number, starts at 1. Default: 1.
• time_range (string, optional): Filter results by time range. One of day, month, year.
• language (string, optional): Language code for results, for example en, fr, de, or all. Default: all.
• safesearch (number, optional): Safe search filter level, where 0 is none, 1 is moderate, and 2 is strict. Defaults to the SearXNG instance setting.
• categories (string, optional): Comma-separated list of search categories to filter results by engine type. Available values: general, images, videos, news, map, music, it, science, files, social media. Defaults to the SearXNG instance setting.

web_url_read

Read and convert the content from a URL to Markdown.

Inputs:

• url (string): The URL to fetch and process.
• startChar (number, optional): Starting character position for content extraction. Default: 0.
• maxLength (number, optional): Maximum number of characters to return.
• section (string, optional): Extract content under a specific heading.
• readHeadings (boolean, optional): Return only a list of headings instead of full content.

Installation

This fork is intended to run with Bun.

git clone https://github.com/tterrasson/mcp-searxng.git
cd mcp-searxng
bun install
bun run build

Use bun dist/index.js in MCP clients after building.

For local development, you can run the TypeScript entrypoint directly:

SEARXNG_URL=http://localhost:8080 bun src/index.ts

HTTP Transport

By default the server uses STDIO. Set MCP_HTTP_PORT to enable HTTP mode:

{
  "mcpServers": {
    "searxng-http": {
      "command": "bun",
      "args": ["/absolute/path/to/mcp-searxng/dist/index.js"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "MCP_HTTP_PORT": "3000"
      }
    }
  }
}

Endpoints:

• POST/GET/DELETE /mcp: MCP protocol
• GET /health: health check

Run it locally:

MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 bun dist/index.js
curl http://localhost:3000/health

Configuration

Set SEARXNG_URL to your SearXNG instance URL. All other variables are optional.

Client compatibility (PLAIN_TEXT_CONTENT)

By default, web_search returns results only via structuredContent (the MCP structured data field). Clients that do not support structuredContent — such as LM Studio — will see an empty response.

Set PLAIN_TEXT_CONTENT to any non-empty value to also include results as plain text in the standard content field:

"env": {
  "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
  "PLAIN_TEXT_CONTENT": "true"
}

Full environment variable reference: CONFIGURATION.md

Troubleshooting

403 Forbidden from SearXNG

Your SearXNG instance likely has JSON format disabled. Edit settings.yml, usually /etc/searxng/settings.yml:

search:
  formats:
    - html
    - json

Restart your SearXNG service, then verify:

curl 'http://localhost:8080/search?q=test&format=json'

You should receive a JSON response. If not, confirm the file is correctly loaded and YAML indentation is valid.

See also: SearXNG settings docs and SearXNG discussion #1789.

Development

bun install
bun run build
bun run lint
bun test tests

Use the MCP inspector:

bun run inspector

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE for details.