SearxNG MCP 서버

SearxNG를 사용하여 웹 검색 기능을 제공하는 MCP(Model Context Protocol) 서버로, Claude와 같은 AI 도우미가 웹을 검색할 수 있습니다.

AI가 인간의 감독 하에 개발했습니다. 인공지능조차도 가끔은 누군가에게 커피 브레이크를 알려줘야 할 때가 있거든요! 🤖☕

개요

이 프로젝트는 개인정보 보호 메타검색 엔진인 SearxNG에 연결되는 MCP 서버를 구현합니다. 이 서버는 대규모 언어 모델(LGM)이 사용자를 추적하지 않고도 웹을 검색할 수 있는 간단하고 효율적인 방법을 제공합니다.

이 서버는 LLM을 위해 특별히 설계되었으며, 컨텍스트 창 사용량을 최소화하는 데 필수적인 기능만 포함합니다. 이러한 간소화된 접근 방식은 LLM과 검색 엔진 간의 효율적인 통신을 보장하고, 더 중요한 정보를 위한 귀중한 컨텍스트 공간을 보존합니다.

특징

SearxNG를 통한 개인 정보 보호 중심 웹 검색
LLM 통합을 위한 간단한 API
Claude Desktop 및 기타 MCP 호환 클라이언트와 호환 가능
구성 가능한 검색 매개변수
LLM에 최적화된 깔끔하고 포맷된 검색 결과

MCP 호환 애플리케이션과의 통합

통합 예제

pipx run 사용 (권장, 설치 불필요)

홈 디렉토리에 .clauderc 파일을 만듭니다.

지엑스피1

uvx run 사용 (설치 필요 없음)

{
  "mcpServers": {
    "searxng": {
      "command": "uvx",
      "args": [
        "run", "searxng-simple-mcp@latest"
      ],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

pip를 사용하여 Python 사용(설치 필요)

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_simple_mcp.server"],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

Docker와 함께 사용(설치 필요 없음)

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "SEARXNG_MCP_SEARXNG_URL=http://localhost:8080",
        "ghcr.io/sacode/searxng-simple-mcp:latest"
      ]
    }
  }
}

참고: MCP 서버와 함께 Docker를 사용하는 경우:

env 객체가 Docker 컨테이너에 제대로 전달되지 않으므로, args 배열에서 -e 플래그를 사용하여 환경 변수를 직접 전달해야 합니다.
로컬호스트(예: http://localhost:8080 )에서 실행 중인 SearxNG 인스턴스에 액세스해야 하는 경우, --network=host 플래그를 사용하여 컨테이너가 호스트 네트워크에 액세스할 수 있도록 허용해야 합니다. 그렇지 않으면 컨테이너 내부의 "localhost"는 호스트 머신이 아닌 컨테이너 자체를 참조합니다.
--network=host 사용하는 경우, 컨테이너가 호스트의 네트워크 스택을 직접 공유하므로 포트 매핑( -p )이 필요하지 않고 무시됩니다.

구성

환경 변수를 사용하여 서버를 구성합니다.

환경 변수	설명	기본값
SEARXNG_MCP_SEARXNG_URL	사용할 SearxNG 인스턴스의 URL	https://paulgo.io/
SEARXNG_MCP_TIMEOUT	HTTP 요청 시간 초과(초)	10
SEARXNG_MCP_기본_결과_카운트	반환할 기본 결과 수	10
SEARXNG_MCP_기본_언어	결과에 대한 언어 코드(예: 'en', 'ru', 'all')	모두
SEARXNG_MCP_기본_포맷	결과에 대한 기본 형식('text', 'json')	텍스트
SEARXNG_MCP_LOG_LEVEL	로깅 수준(예: '디버그', '정보', '경고', '오류', '중요')	오류
운송 프로토콜	전송 프로토콜('stdio' 또는 'sse')	stdio

참고: ERROR(예: DEBUG 또는 INFO)보다 높은 로그 수준을 설정하면 통신 채널에서 과도한 출력이 발생하여 일부 애플리케이션과의 통합이 중단될 수 있습니다.

자체 인스턴스를 호스팅하고 싶지 않다면 https://searx.space 에서 공개 SearxNG 인스턴스 목록을 확인할 수 있습니다.

설치 및 사용

필수 조건

Python 3.10 이상
SearxNG 인스턴스(공개 또는 자체 호스팅)

옵션 1: 설치 없이 실행(권장)

이 서버를 사용하는 가장 쉬운 방법은 pipx 또는 uvx를 사용하는 것입니다. 이를 사용하면 패키지를 영구적으로 설치하지 않고도 실행할 수 있습니다.

# Using pipx
pip install pipx  # Install pipx if you don't have it
pipx run searxng-simple-mcp

# OR using uvx
pip install uvx  # Install uvx if you don't have it
uvx run searxng-simple-mcp

구성 옵션을 직접 전달할 수 있습니다.

# Using pipx with custom SearxNG instance
pipx run searxng-simple-mcp --searxng-url https://your-instance.example.com

옵션 2: PyPI 또는 소스에서 설치

더욱 영구적인 설치를 위해:

# From PyPI using pip
pip install searxng-simple-mcp

# OR using uv (faster installation)
pip install uv
uv pip install searxng-simple-mcp

# OR from source
git clone https://github.com/Sacode/searxng-simple-mcp.git
cd searxng-simple-mcp
pip install uv
uv pip install -e .

설치 후 다음을 사용하여 서버를 실행할 수 있습니다.

# Run directly after installation
python -m searxng_simple_mcp.server

# OR with configuration options
python -m searxng_simple_mcp.server --searxng-url https://your-instance.example.com

옵션 3: Docker

Docker를 사용하는 것을 선호하는 경우:

# Pull the Docker image
docker pull ghcr.io/sacode/searxng-simple-mcp:latest

# Run the container with default settings (stdio transport)
docker run --rm -i ghcr.io/sacode/searxng-simple-mcp:latest

# Run with environment file for configuration
docker run --rm -i --env-file .env ghcr.io/sacode/searxng-simple-mcp:latest

# Run with SSE transport (starts HTTP server on port 8000)
docker run -p 8000:8000 -e TRANSPORT_PROTOCOL=sse ghcr.io/sacode/searxng-simple-mcp:latest

# Building locally
docker build -t searxng-simple-mcp:local .
docker run --rm -i searxng-simple-mcp:local

# Using Docker Compose
docker-compose up -d

Docker 사용에 대한 자세한 내용은 아래의 Docker 구성 섹션을 참조하세요.

전송 프로토콜

MCP 서버는 두 가지 전송 프로토콜을 지원합니다.

STDIO (기본값): CLI 애플리케이션 및 직접 통합용
- 모든 예에서 기본적으로 사용됨
- Claude Desktop 및 기타 MCP 호환 클라이언트와의 통합에 적합
- HTTP 서버가 시작되지 않았습니다.
SSE (Server-Sent Events): 웹 기반 클라이언트 및 HTTP 기반 통합용
- 클라이언트가 연결할 수 있는 HTTP 서버를 시작합니다.
- 실시간 업데이트가 필요한 웹 애플리케이션 및 서비스에 유용합니다.
- Docker를 사용할 때 포트 매핑이 필요합니다.

SSE 전송 사용

SSE 전송 프로토콜을 사용하려면:

직접 실행 :
# Set the transport protocol to SSE TRANSPORT_PROTOCOL=sse python -m searxng_simple_mcp.server # Or with FastMCP fastmcp run src/searxng_simple_mcp/server.py --transport sse
Docker를 사용하여 :
# Run with SSE transport protocol docker run -p 8000:8000 -e TRANSPORT_PROTOCOL=sse -e SEARXNG_MCP_SEARXNG_URL=https://your-instance.example.com ghcr.io/sacode/searxng-simple-mcp:latest
Docker Compose를 사용하는 경우 ( docker-compose.yml 에 포함됨):
environment: - SEARXNG_MCP_SEARXNG_URL=https://searx.info - SEARXNG_MCP_TIMEOUT=10 - SEARXNG_MCP_MAX_RESULTS=20 - SEARXNG_MCP_LANGUAGE=all - TRANSPORT_PROTOCOL=sse # Transport protocol: stdio or sse

SSE를 사용하면 기본적으로 http://localhost:8000 에서 HTTP를 통해 서버에 접근할 수 있습니다.

MCP 클라이언트에서 SSE 서버에 연결하려면 다음과 같은 구성을 사용하세요.

{
  "mcpServers": {
    "searxng": {
      "url": "http://localhost:8000",
      "transport": "sse"
    }
  }
}

참고: 모든 애플리케이션이 SSE 전송 프로토콜을 지원하는 것은 아닙니다. 이 전송 방식을 사용하기 전에 MCP 클라이언트가 SSE와 호환되는지 확인하십시오.

개발

개발 및 테스트를 위해:

# Install dependencies
uv pip install -e .

# Run linter and formatter
ruff check .
ruff check --fix .
ruff format .

# Run the server directly
python -m src.searxng_simple_mcp.server

# OR using FastMCP
fastmcp run src/searxng_simple_mcp/server.py  # Use stdio transport (default)
fastmcp run src/searxng_simple_mcp/server.py --transport sse  # Use sse transport

# Run in development mode (launches MCP Inspector)
fastmcp dev src/searxng_simple_mcp/server.py

PyPI에 게시

PyPI에 패키지의 새 버전을 게시해야 하는 유지 관리자의 경우:

# Install development dependencies
npm run install:deps

# Clean, build, and check the package
npm run build:package
npm run check:package

# Publish to PyPI (requires PyPI credentials)
npm run publish:pypi

# Alternatively, use the all-in-one commands to update version and publish
npm run publish:patch  # Increments patch version (1.0.1 -> 1.0.2)
npm run publish:minor  # Increments minor version (1.0.1 -> 1.1.0)
npm run publish:major  # Increments major version (1.0.1 -> 2.0.0)

이러한 명령은 다음을 수행합니다.

package.json과 pyproject.toml 모두의 버전을 업데이트하세요.
이전 빌드를 제거하려면 dist 디렉토리를 정리하세요.
패키지 빌드(휠 및 소스 배포 생성)
패키지에 오류가 있는지 확인하세요
PyPI에 패키지 업로드

PyPI 계정이 있어야 하며 twine으로 인증을 받아야 합니다. 다음과 같은 방법으로 인증을 설정할 수 있습니다.

홈 디렉토리에 .pypirc 파일 만들기
환경 변수 사용( TWINE_USERNAME 및 TWINE_PASSWORD )
PyPI API 토큰 사용(권장)

Docker 구성

MCP 서버와 함께 Docker를 사용할 때 다음 사항을 염두에 두십시오.

MCP 클라이언트와 통합 : Claude Desktop이나 다른 MCP 호환 클라이언트와 통합하려면 Docker와 함께 사용 섹션에 표시된 구성을 사용하세요.
전송 프로토콜 :
- 기본적으로 Docker 컨테이너는 stdio 전송 프로토콜을 사용합니다.
- SSE 전송의 경우 SSE 전송 사용 섹션을 참조하세요.
구성 옵션 :
- 환경 파일(.env)을 사용하여 서버를 구성합니다: docker run --env-file .env ...
- -e 플래그를 사용하여 개별 환경 변수를 전달합니다: docker run -e SEARXNG_MCP_SEARXNG_URL=https://example.com ...
- 사용 가능한 환경 변수에 대해서는 구성 섹션을 참조하세요.
네트워킹 :
- 호스트 머신에서 서비스에 액세스해야 하는 경우 --network=host 사용하세요.
- 네트워크에 SSE 서버를 노출할 때 -p 8000:8000 사용하세요.

패키지 구조

searxng-simple-mcp/
├── src/
│   ├── run_server.py         # Entry point script
│   └── searxng_simple_mcp/   # Main package
├── docker-compose.yml        # Docker Compose configuration
├── Dockerfile                # Docker configuration
└── pyproject.toml            # Python project configuration

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

SearxNG MCP Server

Integrations