Searxng Mcp

CLI 또는 API | MCP | 에이전트

버전: 2.1.0

문서 — MCP 도구, Python API, 콘솔 스크립트 전반의 설치, 배포, 사용 방법과 SearXNG 인스턴스 프로비저닝에 대한 지침은 공식 문서에서 관리됩니다.

Related MCP server: SearXNG MCP Server

개요

Searxng Mcp는 Agentic AI를 위해 SearXNG Search Engine MCP Server와 직접 인터페이스하도록 설계된 프로덕션 등급의 에이전트 및 Model Context Protocol(MCP) 서버입니다.

주요 기능

• 통합 액션 라우팅 MCP 도구: 메서드를 최적화된 토글 가능한 도구 모듈로 그룹화하여 LLM 컨텍스트의 토큰 오버헤드를 최소화하고 도구 비대화를 제거합니다.

• 엔터프라이즈급 보안: Eunomia 정책, OIDC 토큰 위임, 세분화된 실행 컨텍스트 추적을 포괄적으로 지원합니다.

• 통합 그래프 에이전트: Agent Control Protocol(ACP) 및 표준 웹 인터페이스(AG-UI)를 지원하는 내장 Pydantic AI 에이전트.

• 기본 원격 측정 및 추적: 기본 제공되는 OpenTelemetry 내보내기와 네이티브 Langfuse 추적.

CLI 또는 API

이 에이전트는 Agentic AI! API용 SearXNG Search Engine MCP Server를 래핑합니다. 프로그래밍 방식 또는 통합 실행 진입점을 통해 상호 작용할 수 있습니다.

기본 API 래퍼, 확장 스키마 바인딩, 개발자 SDK 참조 사용 방법에 대한 자세한 지침은 docs/index.md에서 관리됩니다.

MCP

이 서버는 동적 액션 라우팅 도구를 활용하여 토큰 오버헤드를 최적화하고 IDE 호환성을 극대화합니다.

사용 가능한 MCP 도구

아래 표는 MCP 서버에서 자동 생성된 것입니다. 수동으로 편집하지 마십시오.

축약형 액션 라우팅 도구 (MCP_TOOL_MODE=condensed)

액션 라우팅 도구 4개 · 상세 1:1 도구 0개. 각 도구는 해당 <DOMAIN>TOOL 토글이 false로 설정되지 않는 한 활성화됩니다. MCP_TOOL_MODE는 표면을 선택합니다 (**intent 기본값* — 동사 도구 6개, 요청 시 로드되는 세분화된 세트 · condensed 액션 라우팅 · verbose 1:1 · both). 자동 생성됨 — 편집하지 마십시오.*

자세한 도구 스키마, 매개변수 형태, 검증 제약 조건은 docs/usage.md에 보존되어 있습니다.

동적 도구 선택 및 표시 여부

이 MCP 서버는 런타임에 동적 도구 세트 선택 및 표시 여부 필터링을 지원합니다. 이를 통해 노출되는 도구 세트를 제한하여 LLM의 컨텍스트 창이 비대해지는 것을 방지할 수 있습니다.

여러 입력 채널을 통해 도구 필터링을 구성할 수 있습니다:

• CLI 인수: 시작 시 --tools 또는 --toolsets(또는 해당 비활성화 대응 인수인 --disabled-tools 및 --disabled-toolsets)를 전달합니다.

• 환경 변수: 표준 환경 변수를 정의합니다:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• HTTP SSE 요청 헤더: 전송 초기화 중에 사용자 지정 헤더를 전달합니다:

  • x-mcp-enabled-tools / x-mcp-disabled-tools

  • x-mcp-enabled-tags / x-mcp-disabled-tags

• HTTP SSE 요청 쿼리 매개변수: 전송 연결 URL에 쿼리 매개변수를 직접 추가합니다:

  • ?tools=tool1,tool2

  • ?tags=tag1

쿼리 문자열이나 매개변수가 제공되면 LLM이 없는 Knowledge Graph 해석 계층(DynamicToolOrchestrator 사용)이 쿼리 의도를 알려진 도구 태그, 이름 또는 설명과 매칭하며, 안전한 폴백과 자동 24시간 백그라운드 캐시 새로 고침을 제공합니다.

MCP 구성 예시

커넥터 중심의 [mcp] 추가 기능을 설치하세요. 예제에서는 searxng-mcp[mcp]를 사용하여 agent-utilities[mcp]를 통해 FastMCP / FastAPI를 추가합니다. 필수 Agent Utilities 코어는 여전히 epistemic-graph[full]을 포함합니다. [agent-runtime] 추가 기능은 모델 오케스트레이션을 추가로 활성화합니다.

stdio 전송 (로컬 IDE — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "searxng-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "searxng-mcp[mcp]",
        "searxng-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "SEARCH_APPTOOL": "true",
        "SEARXNG_EMBEDDED": "true",
        "SEARXNG_KG_INGEST": "true",
        "USE_RANDOM_INSTANCE": "false"
      }
    }
  }
}

런타임 참조는 GraphOS와 같은 별칭 인식 실행기가 필요합니다. 다른 실행기는 해당 항목을 생략하고 자체 런타임 비밀 경계를 통해 확인된 값을 주입해야 합니다.

Streamable-HTTP 전송 (네트워크 / 프로덕션)

{
  "mcpServers": {
    "searxng-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "searxng-mcp[mcp]",
        "searxng-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "SEARCH_APPTOOL": "true",
        "SEARXNG_EMBEDDED": "true",
        "SEARXNG_KG_INGEST": "true",
        "USE_RANDOM_INSTANCE": "false"
      }
    }
  }
}

또는 url로 사전 배포된 Streamable-HTTP 인스턴스에 연결합니다:

{
  "mcpServers": {
    "searxng-mcp": {
      "url": "http://localhost:8000/searxng-mcp/mcp"
    }
  }
}

검토된 컨테이너 이미지를 최소 권한 stdio 자식 프로세스로 실행합니다(리스너 또는 게시된 포트 없음):

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e SEARCH_APPTOOL=true \
  -e SEARXNG_EMBEDDED=true \
  -e SEARXNG_KG_INGEST=true \
  -e USE_RANDOM_INSTANCE=false \
  registry.example.invalid/searxng-mcp@sha256:<digest> searxng-mcp

컨테이너화된 네트워크 HTTP의 경우 운영자 소유 배포 프로필을 통해 인증된 TLS 인그레스(또는 직접 서버 TLS), 정확한 MCP_ALLOWED_HOSTS, 정확한 신뢰 프록시 CIDR 정책을 제공하십시오. 생성기는 인증되지 않은 비루프백 리스너를 생성하지 않습니다.

코드 판독 환경 표면(MCP_TOOL_MODE + 패키지 변수)에서 자동 생성됨 — 편집하지 마십시오.

추가 배포 옵션

searxng-mcp는 로컬 stdio 프로세스 또는 컨테이너로 실행하거나 원격 네트워크 경계 뒤에서 실행할 수 있습니다. 배포 가이드에 자세한 전송 계약이 나와 있습니다.

• 로컬 컨테이너 — 검토된 불변 이미지를 리스너나 게시된 포트 없이 최소 권한 stdio 자식 프로세스로 실행합니다.

• 원격 URL — 운영자가 제공한 인증된 HTTPS 인그레스를 통해 연결합니다. 해당 URL, 아웃바운드 ID 참조, 신뢰 프로필, 정확한 MCP_ALLOWED_HOSTS를 AgentConfig에 유지합니다.

에이전트

이 저장소는 완전히 통합된 Pydantic AI Graph Agent를 제공합니다. **Agent Control Protocol(ACP)**을 통해 통신하며 Agent Web UI(AG-UI) 및 터미널 인터페이스와 원활하게 상호 작용합니다.

에이전트 CLI 실행

대화형 명령줄 에이전트를 시작하려면:

# Set credentials
export SEARXNG_URL="your_value"

# Run the agent server
searxng-agent --provider openai --model-id gpt-4o

Docker Compose 오케스트레이션

다음 docker/agent.compose.yml은 에이전트, Web UI, 터미널 인터페이스를 함께 구성합니다:

version: '3.8'

services:
  searxng-mcp-mcp:
    image: example/searxng-mcp@sha256:<digest>
    container_name: searxng-mcp-mcp
    hostname: searxng-mcp-mcp
    restart: always
    env_file:
      - ../.env
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=8000
      - TRANSPORT=streamable-http
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  searxng-mcp-agent:
    image: example/searxng-mcp@sha256:<digest>
    container_name: searxng-mcp-agent
    hostname: searxng-mcp-agent
    restart: always
    depends_on:
      - searxng-mcp-mcp
    env_file:
      - ../.env
    command: [ "searxng-agent" ]
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=9001
      - MCP_URL=http://searxng-mcp-mcp:8000/mcp
      - PROVIDER=${PROVIDER:-openai}
      - MODEL_ID=${MODEL_ID:-gpt-4o}
      - ENABLE_WEB_UI=True
      - ENABLE_OTEL=True
    ports:
      - "9001:9001"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9001/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

자세한 그래프 노드 아키텍처 설명, 사용자 지정 스킬 구성, 에이전틱 추적 가이드는 docs/deployment.md에서 확인할 수 있습니다.

보안 및 거버넌스

엔터프라이즈 지원이 가능한 agent-utilities 코어를 기반으로 구축되어 표준 보안 매개변수를 완전히 지원합니다:

액세스 제어 및 정책 시행

• Eunomia 정책: 세분화된 정책 기반 도구 권한 부여. none, 로컬 embedded(mcp_policies.json), 중앙 집중식 remote 모드를 지원합니다.

• OIDC 토큰 위임: Web UI / ACP → 에이전트 → MCP로 인증 사용자 자격 증명을 전달하기 위한 RFC 8693 토큰 교환을 준수합니다.

• 범위 지정 자격 증명: 실행 컨텍스트가 특정 호출자 ID로 제한됩니다.

런타임 보안 그리드

환경 변수

패키지 환경 변수

상속된 agent-utilities 변수(모든 커넥터에 적용)

패키지 20개 + 상속 변수 16개. .env.example + 공유 agent-utilities 세트에서 자동 생성됨 — 편집하지 마세요.

서버가 읽는 모든 변수. 복사-붙여넣기 시작점은 .env.example을 참조하세요.

SearXNG 연결

MCP 서버 / 전송

텔레메트리 및 거버넌스

설치

실행하려는 항목에 맞는 추가 설치를 선택하세요:

# Connector-focused MCP server (includes the shared graph engine)
uv pip install "searxng-mcp[mcp]"

# Agent runtime (adds model orchestration to the shared graph engine)
uv pip install "searxng-mcp[agent]"

# Everything (development)
uv pip install "searxng-mcp[all]"      # or: python -m pip install "searxng-mcp[all]"

컨테이너 이미지(:mcp vs :agent)

하나의 다단계 docker/Dockerfile이 --target으로 선택되는 두 개의 적정 크기 이미지를 빌드합니다:

docker build --target mcp   -t example/searxng-mcp:mcp    docker/   # connector-focused MCP server
docker build --target agent -t example/searxng-mcp:agent-local docker/   # agent runtime

docker/mcp.compose.yml은 커넥터 중심 :mcp 서버를 실행합니다; docker/agent.compose.yml은 공동 배치된 :mcp 사이드카와 함께 에이전트(immutable agent digest)를 실행합니다.

지식 그래프 데이터베이스(epistemic-graph)

[mcp]와 [agent] 모두 필수 Agent Utilities 핵심 종속성(epistemic-graph[full])을 통해 epistemic-graph 엔진을 포함합니다. [mcp] 추가 설치는 서버를 커넥터 중심으로 유지하고; [agent]는 모델 오케스트레이션을 추가로 활성화합니다. 로컬 배포는 번들 엔진을 사용할 수 있습니다. 프로덕션 또는 공유 상태의 경우 epistemic-graph를 전용 데이터베이스 서비스로 실행하고 런타임이 이를 사용하도록 구성하세요. 배포 레시피(단일 노드 + Raft HA), 연결 구성, 아키텍처 다이어그램은 epistemic-graph 배포 가이드에 문서화되어 있습니다.

문서

전체 문서는 공식 문서 사이트에 게시되어 있으며, 설치, 배포, 일상 운영에 대한 권장 참고 자료입니다.

AGENTS.md는 기여자/에이전트를 위한 표준 지침입니다.

저장소 소유자

기여

기여를 환영합니다! 풀 리퀘스트를 제출하기 전에 로컬 검사를 실행하여 코드 품질을 확인해 주세요:

• ruff format .로 코드 서식 지정

• ruff check .로 코드 린트

• mypy .로 타입 안전성 검증

• pytest로 테스트 스위트 실행

agent-utilities-deployment로 배포

통합 agent-utilities-deployment 워크플로로 이 패키지를 프로비저닝하세요. 이 워크플로는 설치된 패키지, 편집 가능한 소스, 또는 불변 컨테이너 경로를 선택하고; 런타임 비밀 및 TLS 프로필 참조만 AgentConfig에 기록하며; doctor, 등록, 정책, 관측 가능성, 롤백 게이트를 실행합니다. 에이전트에게 **"searxng-mcp을 agent-utilities-deployment로 배포"**라고 요청하세요.

저장소에는 배포 프로필, 자격 증명 값, 인증서 경로, 또는 환경별 엔드포인트가 포함되어 있지 않습니다. 런타임에 AgentConfig와 구성된 비밀 공급자를 통해 이를 제공하세요.

거버닝 기능 계약

이 패키지는 전문 절차를 참조 워크플로로 유지하는 간결한 표준 스킬 표면을 제공합니다. 현재 MCP 도구, 스킬 메타데이터, connector_manifest.yml, 온톨로지, 매핑, 셰이프, 픽스처, 마이그레이션, 도구 스키마 지문, 인증 메타데이터는 하나의 버전 관리된 기능 계약을 형성합니다. 이들을 함께 검증하세요; 오래된 도구 이름이나 과거의 작업별 스킬 래퍼에 의존하지 마세요.

런타임 엔드포인트, 자격 증명, 인증서 신뢰, 테넌트 ID, 보존 및 관찰 가능성 정책은 배포 입력값이며 패키징된 값이 아닙니다. 네트워크 전송, 커넥터 수집, GraphOS 위임 또는 트레이스 내보내기를 활성화하기 전에 구성, 신뢰 및 개인정보 보호를 참조하세요.