SearXNG MCP Server

A Model Context Protocol (MCP) server that enables LLMs to search the web using SearXNG meta search engine.

Features

• Web Search: Search across multiple search engines through SearXNG
• Multiple Categories: Support for general, images, videos, news, maps, music, IT, science, files, and social media
• Time Filtering: Filter results by day, week, month, or year
• Language Support: Search in specific languages or auto-detect
• Safe Search: Configurable safe search levels
• Autocomplete: Get search suggestions as you type
• Pagination: Navigate through large result sets
• Multiple Formats: JSON for programmatic use, Markdown for readability
• Dual Transport: Supports both stdio (for MCP) and HTTP modes

Installation

# Install from npm
npm install -g @hu14/searxng-mcp

# Or run with npx
npx @hu14/searxng-mcp

From Source

# Clone or download this repository
cd searxng-mcp

# Install dependencies
npm install

# Build the project
npm run build

Requirements

• Node.js >= 18
• A running SearXNG instance (self-hosted or public)

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SEARXNG_URL | URL of your SearXNG instance | http://localhost:8080 | | TRANSPORT | Transport mode: stdio or http | stdio | | PORT | HTTP server port (when using http transport) | 3000 |

Setting up SearXNG

You need a running SearXNG instance. Options:

1. Self-hosted: Install SearXNG locally
2. Public instance: Use a public SearXNG instance (check searx.space)

For JSON API access, ensure your SearXNG instance has json output format enabled in settings.yml:

search:
  formats:
    - html
    - json

Usage

With Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json or ~/.claude.json):

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "@hu14/searxng-mcp"],
      "env": {
        "SEARXNG_URL": "https://your-searxng-instance.com"
      }
    }
  }
}

Or for local development:

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

With MCP Inspector (for testing)

npx @modelcontextprotocol/inspector npx -y @hu14/searxng-mcp

As HTTP Server

# Using npx
SEARXNG_URL=https://searx.example.com TRANSPORT=http PORT=3000 npx @hu14/searxng-mcp

# Or from source
TRANSPORT=http PORT=3000 node dist/index.js

Available Tools

searxng_search

Search the web using SearXNG.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | query | string | Yes | Search query (1-500 characters) | | category | string | No | Search category: general, images, videos, news, maps, music, it, science, files, social_media | | language | string | No | Language code (e.g., en, zh, de) or auto | | time_range | string | No | Time filter: day, week, month, year | | safesearch | number | No | Safe search level: 0 (off), 1 (moderate), 2 (strict) | | limit | number | No | Max results to return (1-100, default: 20) | | offset | number | No | Skip N results for pagination (default: 0) | | response_format | string | No | Output format: markdown or json |

Examples:

{
  "query": "TypeScript best practices",
  "category": "general",
  "language": "en",
  "limit": 10
}

{
  "query": "artificial intelligence",
  "category": "news",
  "time_range": "week"
}

searxng_autocomplete

Get search suggestions for a partial query.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | query | string | Yes | Partial search query (1-200 characters) | | language | string | No | Language code or auto | | response_format | string | No | Output format: markdown or json |

Response Format

Markdown Format (Default)

Human-readable formatted output with headers, links, and metadata.

JSON Format

Structured data for programmatic processing:

{
  "total": 150,
  "count": 20,
  "offset": 0,
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "content": "Result description...",
      "engine": "google",
      "publishedDate": "2024-01-15"
    }
  ],
  "suggestions": ["related query 1", "related query 2"],
  "has_more": true,
  "next_offset": 20
}

Development

# Clone the repository
git clone <repository-url>
cd searxng-mcp

# Install dependencies
npm install

# Development with auto-reload
npm run dev

# Build
npm run build

# Clean build artifacts
npm run clean

Changelog

See CHANGELOG.md for version history.

License

MIT