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.
URL Content Reading: Advanced content extraction with pagination, section filtering, and heading extraction.
Intelligent Caching: URL content is cached with TTL (Time-To-Live) to improve performance and reduce redundant requests.
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 with advanced content extraction options
- Inputs:
  - url (string): The URL to fetch and process
  - startChar (number, optional): Starting character position for content extraction (default: 0)
  - maxLength (number, optional): Maximum number of characters to return
  - section (string, optional): Extract content under a specific heading (searches for heading text)
  - paragraphRange (string, optional): Return specific paragraph ranges (e.g., '1-5', '3', '10-')
  - readHeadings (boolean, optional): Return only a list of headings instead of full content

Configuration

Setting the SEARXNG_URL

The SEARXNG_URL environment variable defines which SearxNG instance to connect to.

Environment Variable Format

SEARXNG_URL=<protocol>://<hostname>[:<port>]

Examples

# Local development (default)
SEARXNG_URL=http://localhost:8080

# Public instance
SEARXNG_URL=https://search.example.com

# Custom port
SEARXNG_URL=http://my-searxng.local:3000

Setup Instructions

Choose a SearxNG instance from the list of public instances or use your local environment
Set the SEARXNG_URL environment variable to the complete instance URL
If not specified, the default value http://localhost:8080 will be used

Using Authentication (Optional)

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

Set the AUTH_USERNAME environment variable to your username
Set the AUTH_PASSWORD environment variable to your password

Note: Authentication is only required for password-protected SearxNG instances. See the usage examples below for how to configure authentication with different installation methods.

Proxy Support (Optional)

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
NO_PROXY: Comma-separated list of hostnames or domains to bypass proxy
no_proxy: Alternative lowercase version for NO_PROXY

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:[email protected]:8080
export HTTPS_PROXY=http://username:[email protected]:8080

# Proxy with NO_PROXY bypass list
export HTTP_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.local,.internal,example.com

NO_PROXY Format

The NO_PROXY variable accepts a comma-separated list of hosts and domains that should bypass the proxy:

Exact hostname: example.com - matches only example.com
Domain suffix: .example.com or example.com - matches sub.example.com, api.example.com, etc.
Localhost: localhost, 127.0.0.1 - common for local development
Wildcard: * - bypasses proxy for all requests (not recommended)

Examples:

# Bypass proxy for localhost and internal domains
export NO_PROXY=localhost,127.0.0.1,.internal,.local

# Bypass proxy for specific services
export NO_PROXY=api.company.com,search.internal

# Multiple formats combined
export NO_PROXY=localhost,*.local,.internal,192.168.1.0/24

Note: If no proxy environment variables are set, the server will make direct connections as normal. See the usage examples below for how to configure proxy settings with different installation methods.

NPX

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

Additional NPX Configuration Options

With Authentication

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

With Proxy Support

{
  "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 Proxy and NO_PROXY Support

{
  "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",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

With Authentication and Proxy Support

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

With Authentication, Proxy, and NO_PROXY Support

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

NPM

npm install -g mcp-searxng

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

Additional NPM Configuration Options

With Authentication

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password"
      }
    }
  }
}

With Proxy Support

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

With Proxy and NO_PROXY Support

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

With Authentication and Proxy Support

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080"
      }
    }
  }
}

With Authentication, Proxy, and NO_PROXY Support

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

With Authentication and Proxy Support

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080"
      }
    }
  }
}

Docker

Using Pre-built Image from Docker Hub

docker pull isokoliuk/mcp-searxng:latest

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

Additional Docker Configuration Options

With Authentication

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "-e", "AUTH_USERNAME",
        "-e", "AUTH_PASSWORD",
        "isokoliuk/mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password"
      }
    }
  }
}

With Proxy Support

{
  "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"
      }
    }
  }
}

With Proxy and NO_PROXY Support

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_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",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

With Authentication and Proxy Support

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

With Authentication, Proxy, and NO_PROXY Support

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "-e", "AUTH_USERNAME",
        "-e", "AUTH_PASSWORD",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_PROXY",
        "isokoliuk/mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

Build Locally

docker build -t mcp-searxng:latest -f Dockerfile .

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

Additional Build Locally Configuration Options

With Authentication

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

With Proxy Support

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

With Proxy and NO_PROXY Support

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

With Authentication and Proxy Support

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

With Authentication, Proxy, and NO_PROXY Support

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "-e", "AUTH_USERNAME",
        "-e", "AUTH_PASSWORD",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_PROXY",
        "mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

Docker Compose

Create a docker-compose.yml file:

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL

Then configure your MCP client:

{
  "mcpServers": {
    "searxng": {
      "command": "docker-compose",
      "args": ["run", "--rm", "mcp-searxng"]
    }
  }
}

Additional Docker Compose Configuration Options

With Authentication

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL
      - AUTH_USERNAME=your_username
      - AUTH_PASSWORD=your_password

With Proxy Support

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL
      - HTTP_PROXY=http://proxy.company.com:8080
      - HTTPS_PROXY=http://proxy.company.com:8080

With Proxy and NO_PROXY Support

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL
      - HTTP_PROXY=http://proxy.company.com:8080
      - HTTPS_PROXY=http://proxy.company.com:8080
      - NO_PROXY=localhost,127.0.0.1,.local,.internal

With Authentication and Proxy Support

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL
      - AUTH_USERNAME=your_username
      - AUTH_PASSWORD=your_password
      - HTTP_PROXY=http://proxy.company.com:8080
      - HTTPS_PROXY=http://proxy.company.com:8080

With Authentication, Proxy, and NO_PROXY Support

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL
      - AUTH_USERNAME=your_username
      - AUTH_PASSWORD=your_password
      - HTTP_PROXY=http://proxy.company.com:8080
      - HTTPS_PROXY=http://proxy.company.com:8080
      - NO_PROXY=localhost,127.0.0.1,.local,.internal

Using Local Build

services:
  mcp-searxng:
    build: .
    stdin_open: true
    environment:
      - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL

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

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

Additional HTTP Transport Configuration Options

HTTP Server with Authentication

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

HTTP Server with Proxy Support

{
  "mcpServers": {
    "searxng-http": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "MCP_HTTP_PORT": "3000",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080"
      }
    }
  }
}

HTTP Server with Proxy and NO_PROXY Support

{
  "mcpServers": {
    "searxng-http": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "MCP_HTTP_PORT": "3000",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

HTTP Server with Authentication and Proxy Support

{
  "mcpServers": {
    "searxng-http": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "MCP_HTTP_PORT": "3000",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080"
      }
    }
  }
}

HTTP Server with Authentication, Proxy, and NO_PROXY Support

{
  "mcpServers": {
    "searxng-http": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "MCP_HTTP_PORT": "3000",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

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

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:

0. Coding Guidelines

Use TypeScript for type safety
Follow existing error handling patterns
Keep error messages concise but informative
Write unit tests for new functionality
Ensure all tests pass before submitting PRs
Maintain test coverage above 90%
Test changes with the MCP inspector
Run evals before submitting PRs

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

3. Development Workflow

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes in src/ directory
- Main server logic: src/index.ts
- Error handling: src/error-handler.ts

Build and test:

npm run build               # Build the project
npm test                     # Run unit tests
npm run test:coverage       # Run tests with coverage report
npm run inspector            # Run MCP inspector

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

Testing

The project includes comprehensive unit tests with excellent coverage.

Running Tests

# Run all tests
npm test

# Run with coverage reporting
npm run test:coverage

# Watch mode for development
npm run test:watch

Test Statistics

Unit tests covering all core modules
100% success rate with dynamic coverage reporting via c8
HTML coverage reports generated in coverage/ directory

What's Tested

Error handling (network, server, configuration errors)
Type validation and schema guards
Proxy configurations and environment variables
Resource generation and logging functionality
All module imports and function availability

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.

Name		Name	Last commit message	Last commit date
Latest commit History 139 Commits
.github/workflows		.github/workflows
__tests__		__tests__
scripts		scripts
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
evals.ts		evals.ts
package.json		package.json
tsconfig.json		tsconfig.json

License

ihor-sokoliuk/mcp-searxng

Folders and files

Latest commit

History

Repository files navigation

SearXNG MCP Server

Features

Tools

Configuration

Setting the SEARXNG_URL

Environment Variable Format

Examples

Setup Instructions

Using Authentication (Optional)

Proxy Support (Optional)

Proxy Environment Variables

Proxy URL Formats

NO_PROXY Format

NPX

With Authentication

With Proxy Support

With Proxy and NO_PROXY Support

With Authentication and Proxy Support

With Authentication, Proxy, and NO_PROXY Support

NPM

With Authentication

With Proxy Support

With Proxy and NO_PROXY Support

With Authentication and Proxy Support

With Authentication, Proxy, and NO_PROXY Support

With Authentication and Proxy Support

Docker

Using Pre-built Image from Docker Hub

With Authentication

With Proxy Support

With Proxy and NO_PROXY Support

With Authentication and Proxy Support

With Authentication, Proxy, and NO_PROXY Support

Build Locally

With Authentication

With Proxy Support

With Proxy and NO_PROXY Support

With Authentication and Proxy Support

With Authentication, Proxy, and NO_PROXY Support

Docker Compose

With Authentication

With Proxy Support

With Proxy and NO_PROXY Support

With Authentication and Proxy Support

With Authentication, Proxy, and NO_PROXY Support

Using Local Build

HTTP Transport (Optional)

STDIO Transport (Default)

HTTP Transport

HTTP Server with Authentication

HTTP Server with Proxy Support

HTTP Server with Proxy and NO_PROXY Support

HTTP Server with Authentication and Proxy Support

HTTP Server with Authentication, Proxy, and NO_PROXY Support

Running evals

For Developers

Contributing to the Project

0. Coding Guidelines

1. Fork and Clone

2. Development Setup

3. Development Workflow

4. Submitting Changes

Testing

Running Tests

Test Statistics

What's Tested

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Packages