SearXNG MCP Server

A bridge to use SearXNG as an MCP server from Claude Code.

Features

searxng_search: Web search with multiple engines
searxng_images: Image search
searxng_news: News search

Prerequisites

SearXNG instance running with JSON format enabled

Important: SearXNG's default configuration only allows HTML format. To use this MCP server, you must enable JSON format by mounting a custom configuration file.

First, create your configuration file from the example:

cp searxng-config/settings.yml.example searxng-config/settings.yml
# Edit settings.yml to set your own secret_key

Then start SearXNG with the configuration:

# Using Docker (recommended)
docker run -d \
  -p 8080:8080 \
  -v $(pwd)/searxng-config/settings.yml:/etc/searxng/settings.yml:ro \
  -e SEARXNG_BASE_URL=http://localhost:8080/ \
  searxng/searxng

# Or install locally
# See: https://docs.searxng.org/admin/installation.html

The searxng-config/settings.yml.example file includes the necessary configuration to enable JSON format:

use_default_settings: true

search:
  formats:
    - html
    - json

server:
  secret_key: "your-secret-key-here"
  limiter: false
  image_proxy: true

Verify SearXNG is running with JSON format enabled
```
curl "http://localhost:8080/search?q=test&format=json"
```
If you get a 403 Forbidden error, the JSON format is not enabled. Make sure you mounted the configuration file correctly.

Installation

cd searxng-mcp-server
npm install
npm run build

Claude Code Configuration

Method 1: Using CLI (Recommended)

# Add to local scope (current project)
claude mcp add --transport stdio searxng -- node /path/to/searxng-mcp-server/dist/index.js

# Add to user scope (all projects)
claude mcp add --transport stdio searxng --scope user -- node /path/to/searxng-mcp-server/dist/index.js

To add environment variables:

claude mcp add --transport stdio searxng \
  --env SEARXNG_BASE_URL=http://localhost:8080 \
  -- node /path/to/searxng-mcp-server/dist/index.js

Method 2: Manual Configuration

Project scope (.mcp.json in project root):

{
  "mcpServers": {
    "searxng": {
      "command": "node",
      "args": ["/path/to/searxng-mcp-server/dist/index.js"],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:8080"
      }
    }
  }
}

User scope (~/.claude.json):

{
  "mcpServers": {
    "searxng": {
      "command": "node",
      "args": ["/path/to/searxng-mcp-server/dist/index.js"],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:8080"
      }
    }
  }
}

Verify Installation

# List configured MCP servers
claude mcp list

# Inside Claude Code
/mcp

Auto-approve Tool Calls (Optional)

By default, Claude Code asks for confirmation each time a SearXNG tool is called. To skip confirmations, add the following to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__searxng__searxng_search",
      "mcp__searxng__searxng_images",
      "mcp__searxng__searxng_news"
    ]
  }
}

Environment Variables

Variable	Default	Description
`SEARXNG_BASE_URL`	`http://localhost:8080`	SearXNG server URL

Usage Examples

From Claude Code:

Web Search

Search for "Rust programming language features" using SearXNG

Image Search

Find images of "Mount Fuji" using SearXNG

News Search

Get latest news about "AI developments" using SearXNG

Troubleshooting

403 Forbidden error with JSON format

If you get a 403 Forbidden error when using format=json, the JSON format is not enabled in your SearXNG instance. Make sure you:

Mount the configuration file when starting Docker:

docker run -d \
  -p 8080:8080 \
  -v $(pwd)/searxng-config/settings.yml:/etc/searxng/settings.yml:ro \
  -e SEARXNG_BASE_URL=http://localhost:8080/ \
  searxng/searxng

Verify the configuration includes JSON format:

docker exec <container_id> grep -A 3 "formats" /etc/searxng/settings.yml

Cannot connect to SearXNG

# Check if SearXNG is running
curl "http://localhost:8080/search?q=test&format=json"

# If not running (Docker) - make sure to mount the config file
docker run -d \
  -p 8080:8080 \
  -v $(pwd)/searxng-config/settings.yml:/etc/searxng/settings.yml:ro \
  -e SEARXNG_BASE_URL=http://localhost:8080/ \
  searxng/searxng

No results returned

SearXNG aggregates results from multiple search engines. If no results are returned:

Check if your SearXNG instance has engines enabled
Try specifying engines: engines: "google,bing,duckduckgo"
Check SearXNG logs for errors

MCP server not showing up

# Verify server is registered
claude mcp list

# Check server health
claude mcp get searxng

License

MIT