Skip to main content
Glama

SearXNG Server

SearXNG MCP Server

An MCP server implementation that integrates the SearXNG API, providing web search capabilities.

Features

  • Web Search: General queries, news, articles, with pagination.
  • Pagination: Control which page of results to retrieve.
  • Time Filtering: Filter results by time range (day, month, year).
  • Language Selection: Filter results by preferred language.
  • Safe Search: Control content filtering level for search results.

Tools

  • searxng_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" (default: none)
      • language (string, optional): Language code for results (e.g., "en", "fr", "de") or "all" (default: "all")
      • safesearch (number, optional): Safe search filter level (0: None, 1: Moderate, 2: Strict) (default: instance setting)
  • web_url_read
    • Read and convert the content from a URL to markdown
    • Inputs:
      • url (string): The URL to fetch and process

Configuration

Setting the SEARXNG_URL

  1. Choose a SearxNG instance from the list of public instances or use your local environment.
  2. Set the SEARXNG_URL environment variable to the instance URL.
  3. The default SEARXNG_URL value is http://localhost:8080.

Using Authentication

If you are using a password protected SearxNG instance you can set a username and password for HTTP Basic Auth:

  • Set the AUTH_USERNAME environmental variable to your username
  • Set the AUTH_PASSWORD environmental variable to your password

Proxy Support

The server supports HTTP and HTTPS proxies through environment variables. This is useful when running behind corporate firewalls or when you need to route traffic through a specific proxy server.

Proxy Environment Variables

Set one or more of these environment variables to configure proxy support:

  • HTTP_PROXY: Proxy URL for HTTP requests
  • HTTPS_PROXY: Proxy URL for HTTPS requests
  • http_proxy: Alternative lowercase version for HTTP requests
  • https_proxy: Alternative lowercase version for HTTPS requests
Proxy URL Formats

The proxy URL can be in any of these formats:

# Basic proxy export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=http://proxy.company.com:8080 # Proxy with authentication export HTTP_PROXY=http://username:password@proxy.company.com:8080 export HTTPS_PROXY=https://username:password@proxy.company.com:8080
Usage Examples

With NPX:

{ "mcpServers": { "searxng": { "command": "npx", "args": ["-y", "mcp-searxng"], "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL", "HTTP_PROXY": "http://proxy.company.com:8080", "HTTPS_PROXY": "http://proxy.company.com:8080" } } } }

With Docker:

{ "mcpServers": { "searxng": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "SEARXNG_URL", "-e", "HTTP_PROXY", "-e", "HTTPS_PROXY", "isokoliuk/mcp-searxng:latest" ], "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL", "HTTP_PROXY": "http://proxy.company.com:8080", "HTTPS_PROXY": "http://proxy.company.com:8080" } } } }

Note: If no proxy environment variables are set, the server will make direct connections as normal.

HTTP Transport (Optional)

The server supports both STDIO (default) and HTTP transports:

STDIO Transport (Default)
  • Best for: Claude Desktop and most MCP clients
  • Usage: Automatic - no additional configuration needed
HTTP Transport
  • Best for: Web-based applications and remote MCP clients
  • Usage: Set the MCP_HTTP_PORT environment variable

HTTP Server Configuration:

{ "mcpServers": { "searxng-http": { "command": "mcp-searxng", "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL", "MCP_HTTP_PORT": "3000" } } } }

HTTP Endpoints:

  • MCP Protocol: POST/GET/DELETE /mcp
  • Health Check: GET /health
  • CORS: Enabled for web clients

Testing HTTP Server:

# Start HTTP server MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng # Check health curl http://localhost:3000/health

Usage with Claude Desktop

Installing via Smithery

To install SearxNG Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @ihor-sokoliuk/server-searxng --client claude

NPX

{ "mcpServers": { "searxng": { "command": "npx", "args": [ "-y", "mcp-searxng" ], "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL" } } } }

NPM

npm install -g mcp-searxng

And then in your MCP config file:

{ "mcpServers": { "searxng": { "command": "mcp-searxng", "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL" } } } }

Docker

Using Pre-built Image from Docker Hub
docker pull isokoliuk/mcp-searxng:latest

Add this to your claude_desktop_config.json:

{ "mcpServers": { "searxng": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "SEARXNG_URL", "isokoliuk/mcp-searxng:latest" ], "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL" } } } }
Build Locally
docker build -t mcp-searxng:latest -f Dockerfile .
Use

Add this to your claude_desktop_config.json:

{ "mcpServers": { "searxng": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "SEARXNG_URL", "mcp-searxng:latest" ], "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL" } } } }

Running evals

The evals package loads an mcp client that then runs the src/index.ts file, so there is no need to rebuild between tests. You can see the full documentation here.

SEARXNG_URL=SEARXNG_URL OPENAI_API_KEY=your-key npx mcp-eval evals.ts src/index.ts

For Developers

Contributing to the Project

We welcome contributions! Here's how to get started:

1. Fork and Clone
# Fork the repository on GitHub, then clone your fork git clone https://github.com/YOUR_USERNAME/mcp-searxng.git cd mcp-searxng # Add the original repository as upstream git remote add upstream https://github.com/ihor-sokoliuk/mcp-searxng.git
2. Development Setup
# Install dependencies npm install # Start development with file watching npm run watch # Test the server with inspector npm run inspector
3. Development Workflow
  1. Create a feature branch:
    git checkout -b feature/your-feature-name
  2. Make your changes in src/ directory
    • Main server logic: src/index.ts
    • Error handling: src/error-handler.ts
  3. Build and test:
    npm run build npm run inspector
  4. Run evals to ensure functionality:
    SEARXNG_URL=http://localhost:8080 OPENAI_API_KEY=your-key npx mcp-eval evals.ts src/index.ts
4. Submitting Changes
# Commit your changes git add . git commit -m "feat: description of your changes" # Push to your fork git push origin feature/your-feature-name # Create a Pull Request on GitHub

Version Management & Releases

For Maintainers: Bumping Versions

The project uses semantic versioning. Use npm's version command to bump versions properly:

# Patch release (0.6.0 → 0.6.1) - bug fixes npm version patch # Minor release (0.6.0 → 0.7.0) - new features npm version minor # Major release (0.6.0 → 1.0.0) - breaking changes npm version major

The postversion script automatically:

  • Updates the version in src/index.ts
  • Stages the changes
  • Amends the version commit
Creating Release Tags

After bumping the version:

# Push the version commit and tag git push origin main --tags # Or push everything at once git push origin main --follow-tags
Publishing to NPM
# Build the project npm run build # Publish to NPM (make sure you're logged in) npm publish
Docker Release
# Build and tag the Docker image docker build -t isokoliuk/mcp-searxng:latest . docker build -t isokoliuk/mcp-searxng:v$(node -p "require('./package.json').version") . # Push to Docker Hub docker push isokoliuk/mcp-searxng:latest docker push isokoliuk/mcp-searxng:v$(node -p "require('./package.json').version")

Project Structure

mcp-searxng/ ├── src/ │ ├── index.ts # Main MCP server implementation │ └── error-handler.ts # Error handling utilities ├── scripts/ │ └── update-version.js # Version update script ├── dist/ # Built JavaScript files ├── Dockerfile # Docker configuration ├── package.json # Project configuration └── tsconfig.json # TypeScript configuration

Coding Guidelines

  • Use TypeScript for type safety
  • Follow existing error handling patterns
  • Keep error messages concise but informative
  • Add appropriate emoji indicators for error categories
  • Test changes with the MCP inspector
  • Run evals before submitting PRs

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

An MCP server implementation that integrates the SearXNG API, providing web search capabilities.

  1. Features
    1. Tools
      1. Configuration
        1. Setting the SEARXNG_URL
        2. Usage with Claude Desktop
        3. Installing via Smithery
        4. NPX
        5. NPM
        6. Docker
      2. License

        Related MCP Servers

        • A
          security
          A
          license
          A
          quality
          An MCP server for connecting agentic systems to search systems via searXNG.
          Last updated -
          1
          96
          MIT License
        • -
          security
          F
          license
          -
          quality
          An MCP server that integrates with SerpApi to retrieve search results from multiple search engines including Google, Bing, Yahoo, and others, enabling fast access to both live and archived search data.
          Last updated -
          14
        • -
          security
          A
          license
          -
          quality
          An MCP server that enables web searches using a SearxNG instance, allowing MCP-compatible applications like Goose to perform internet searches.
          Last updated -
          GPL 3.0
        • A
          security
          A
          license
          A
          quality
          An MCP server that allows searching through public SearXNG instances by parsing HTML content into JSON results, enabling metasearch capabilities without requiring JSON API access.
          Last updated -
          1
          150
          17
          MIT License

        View all related MCP servers

        MCP directory API

        We provide all the information about MCP servers via our MCP API.

        curl -X GET 'https://glama.ai/api/mcp/v1/servers/ihor-sokoliuk/mcp-searxng'

        If you have feedback or need assistance with the MCP directory API, please join our Discord server