Skip to main content
Glama
enesjakozh
Sacode

SearxNG MCP Server

by Sacode
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

SearxNG MCP 서버

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

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

개요

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

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

특징

  • SearxNG를 통한 개인 정보 보호 중심 웹 검색

  • LLM 통합을 위한 간단한 API

  • Claude Desktop 및 기타 MCP 호환 클라이언트와 호환 가능

  • 구성 가능한 검색 매개변수

  • LLM에 최적화된 깔끔하고 포맷된 검색 결과

Related MCP server: mcp-searxng

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를 사용하는 경우:

  1. env 객체가 Docker 컨테이너에 제대로 전달되지 않으므로, args 배열에서 -e 플래그를 사용하여 환경 변수를 직접 전달해야 합니다.

  2. 로컬호스트(예: http://localhost:8080 )에서 실행 중인 SearxNG 인스턴스에 액세스해야 하는 경우, --network=host 플래그를 사용하여 컨테이너가 호스트 네트워크에 액세스할 수 있도록 허용해야 합니다. 그렇지 않으면 컨테이너 내부의 "localhost"는 호스트 머신이 아닌 컨테이너 자체를 참조합니다.

  3. --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 전송 프로토콜을 사용하려면:

  1. 직접 실행 :

    # 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

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

  3. 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)

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

  1. package.json과 pyproject.toml 모두의 버전을 업데이트하세요.

  2. 이전 빌드를 제거하려면 dist 디렉토리를 정리하세요.

  3. 패키지 빌드(휠 및 소스 배포 생성)

  4. 패키지에 오류가 있는지 확인하세요

  5. PyPI에 패키지 업로드

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

  • 홈 디렉토리에 .pypirc 파일 만들기

  • 환경 변수 사용( TWINE_USERNAME 및 TWINE_PASSWORD )

  • PyPI API 토큰 사용(권장)

Docker 구성

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

  1. MCP 클라이언트와 통합 : Claude Desktop이나 다른 MCP 호환 클라이언트와 통합하려면 Docker와 함께 사용 섹션에 표시된 구성을 사용하세요.

  2. 전송 프로토콜 :

    • 기본적으로 Docker 컨테이너는 stdio 전송 프로토콜을 사용합니다.

    • SSE 전송의 경우 SSE 전송 사용 섹션을 참조하세요.

  3. 구성 옵션 :

    • 환경 파일(.env)을 사용하여 서버를 구성합니다: docker run --env-file .env ...

    • -e 플래그를 사용하여 개별 환경 변수를 전달합니다: docker run -e SEARXNG_MCP_SEARXNG_URL=https://example.com ...

    • 사용 가능한 환경 변수에 대해서는 구성 섹션을 참조하세요.

  4. 네트워킹 :

    • 호스트 머신에서 서비스에 액세스해야 하는 경우 --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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

Available Tools

1 tool

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • Changedweb_search3 fields changed
      • changedInput schema / properties / result_format / description
        Previous value: -"Output format - 'text' for human-readable or 'json' for structured data"New value: +"Output format - 'text' for human-readable, 'json' for structured data"
      • removedInput schema / title
        Removed value: -"web_searchArguments"
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$defs": {
+    "SearxngResult": {
+      "description": "Model for a single SearxNG search result.",
+      "properties": {
+        "category": {
+          "title": "Category",
+          "type": "string"
+        },
+        "content": {
+          "title": "Content",
+          "type": "string"
+        },
+        "engine": {
+          "title": "Engine",
+          "type": "string"
+        },
+        "engines": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Engines",
+          "type": "array"
+        },
+        "img_src": {
+          "title": "Img Src",
+          "type": "string"
+        },
+        "parsed_url": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Parsed Url",
+          "type": "array"
+        },
+        "positions": {
+          "items": {
+            "type": "integer"
+          },
+          "title": "Positions",
+          "type": "array"
+        },
+        "priority": {
+          "title": "Priority",
+          "type": "string"
+        },
+        "publishedDate": {
+          "default": null,
+          "title": "Publisheddate"
+        },
+        "score": {
+          "title": "Score",
+          "type": "number"
+        },
+        "template": {
+          "title": "Template",
+          "type": "string"
+        },
+        "thumbnail": {
+          "default": null,
+          "title": "Thumbnail"
+        },
+        "title": {
+          "title": "Title",
+          "type": "string"
+        },
+        "url": {
+          "title": "Url",
+          "type": "string"
+        }
+      },
+      "required": [
+        "url",
+        "title",
+        "content",
+        "engine",
+        "template",
+        "parsed_url",
+        "img_src",
+        "priority",
+        "engines",
+        "positions",
+        "score",
+        "category"
+      ],
+      "title": "SearxngResult",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "result": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "items": {
+            "$ref": "#/$defs/SearxngResult"
+          },
+          "type": "array"
+        }
+      ],
+      "title": "Result"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "_WrappedResult",
+  "type": "object",
+  "x-fastmcp-wrap-result": true
+}
  2. 1 tool update
    • First observedweb_search
Deploy Server
Give agents eyes on the webHosted screenshot MCP. Send a URL, get a pixel-perfect image. $0.002 per grab. Works with Claude, Cursor, and Codex.grabbit.liveAd

TDQS

B3.1/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool 'web_search' has a clearly defined and distinct purpose.

Naming Consistency5/5

Since there is only one tool, naming consistency is inherently perfect. The tool name 'web_search' follows a clear verb_noun pattern and is descriptive.

Tool Count2/5

A single tool is too few for a server named 'SearxNG MCP Server', which suggests a broader search functionality. While web search is core, the scope feels thin without additional tools like image_search, news_search, or configuration options.

Completeness2/5

The tool surface is severely incomplete for a search server. It only covers basic web search, missing obvious functionalities such as image search, news search, or advanced search parameters that would be expected from a search engine integration.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • SearXNG MCP Server

    ngc-shj
    A
    license
    A
    quality
    D
    maintenance
    Enables web search, image search, and news search through a self-hosted SearXNG instance. Provides privacy-focused meta-search capabilities aggregating results from multiple search engines.
    3
    153 npm
    1
    MIT

  • mcp-searxng

    kassol
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to perform web searches and read URL content via a SearXNG instance.
    2
    18 npm
    MIT

  • web-search-mcp

    Backerss
    F
    license
    Not graded
    quality
    D
    maintenance
    Provides free web search, content fetching, image search, and deep research via SearXNG, no API keys required.
    -

Appeared in Searches