searxng-mcp-server

SearXNG MCP Server

Privacy-focused web search via SearXNG for Model Context Protocol (MCP) clients.

Features

• Streamable HTTP transport - Single HTTP endpoint for MCP communication
• SearXNG integration - Privacy-focused search engine
• Docker ready - Easy deployment with Docker Compose
• TypeScript - Type-safe implementation

Quick Start

1. Start the server

You can start the server using one of the following Docker Compose configurations:

Standard Usage (compose.yml)

Uses the pre-built image from GitHub Container Registry. Recommended if you already have a SearXNG instance running (default: http://localhost:8080).

docker compose up -d

Development & Build (compose.dev.yml)

Builds the image from the local source code. Use this for development or if you want to modify the source.

docker compose -f compose.dev.yml up -d --build

Production / Full Stack (compose.prod.yml)

Launches a complete stack including SearXNG, Nginx, and the MCP server. Use this if you don't have a SearXNG instance running yet. This setup includes:

• searxng: SearXNG search engine instance
• searxng-mcp-server: MCP server
• nginx: Reverse proxy

docker compose -f compose.prod.yml up -d

2. Verify the server is running

curl http://localhost:3000/health

Expected response: ``json { "status": "ok", "timestamp": "2026-02-15T04:10:23.000Z", "service": "searxng-mcp-server" } ``

3. Enable JSON output in SearXNG

If you are running your own SearXNG instance (especially via Docker Compose), you might encounter a 403 Forbidden error when the MCP server tries to fetch search results. This happens because JSON output is disabled by default in SearXNG.

To fix this, edit your SearXNG's settings.yml and add json to the search formats:

search:
  formats:
    - html
    - json  # Add this line to enable JSON output

Restart your SearXNG container after making this change.

4. Configure your MCP client

Claude Code

Run the following command in Claude Code:

claude mcp add --transport http searxng http://localhost:3000/mcp

Or add to ~/.claude.json

{
  "mcpServers": {
    "searxng": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Then restart Claude Desktop.

Cline

Add to your Cline configuration file:

{
  "mcpServers": {
    "searxng": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Available Tools

searxng_search

Perform web searches using SearXNG.

Parameters:

• query (required): Search query string
• category (optional): Search category - general, images, videos, files, news, map, music, social media (default: general)
• language (optional): Language code (default: all)
• time_range (optional): Time filter - day, week, month, year
• safesearch (optional): Safe search level - 0 (off), 1 (moderate), 2 (strict) (default: 1)

Example: ``json { "query": "TypeScript MCP server", "category": "general", "language": "ja" } ``

Response includes:

• Search results with title, URL, content, score, category, published date
• Suggestions for related searches
• Search metadata (number of results, response time)

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SEARXNG_URL | SearXNG instance URL | http://localhost:8080 | | SERVER_PORT | HTTP server port | 3000 | | SERVER_HOST | HTTP server host | 0.0.0.0 | | LOG_LEVEL | Logging level | info |

Development

Prerequisites

• Node.js 24+
• pnpm 9.15.4+

Install dependencies

pnpm install

Build

pnpm build

Run in development mode

pnpm dev

Run in production mode

pnpm start

Testing

MCP Inspector

MCP Inspector is a web-based tool for debugging and exploring MCP servers.

Test MCP connection

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

Test search tool

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"searxng_search","arguments":{"query":"test query"}}}'

License

This project is released under the MIT License.