SearXNG MCP Server

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

日本語版 README はこちら

Features

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

Prerequisites

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

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

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:

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

2. 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:

1. Check if your SearXNG instance has engines enabled
2. Try specifying engines: engines: "google,bing,duckduckgo"
3. 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