SearXNG MCP Server

FastMCP를 기반으로 구현된 SearXNG 검색 MCP 서비스로, Streamable HTTP 전송을 사용하며 로컬 실행과 Docker 배포를 지원합니다.

SearXNG 관련 링크:

공식 문서: https://docs.searxng.org/

온라인 예시: https://searx.space/

기능

• MCP 도구 search(query) 노출: 키워드로 SearXNG 인스턴스를 호출하고 검색 결과 요약을 반환합니다.

• HTTP 엔드포인트 http://<host>:<port>/mcp를 통해 MCP 서비스를 제공하여 원격/크로스 도메인 호출을 지원합니다.

• 무상태(stateless) Streamable HTTP 모드를 채택하여 클라이언트가 Mcp-Session-Id를 유지할 필요 없이 바로 동시 호출할 수 있습니다.

• 환경 변수를 통한 SearXNG 인스턴스 주소 사용자 지정을 지원하여 프라이빗 배포에 용이합니다.

Related MCP server: SearXNG MCP Server

환경 변수

로컬 실행

# 安装依赖（建议使用虚拟环境）
pip install -r requirements.txt

# 可选：自定义 SearXNG 实例（只需填根地址）
export SEARXNG_URL="https://your-searxng-instance"

# 启动服务
python Server.py

시작 후 MCP 엔드포인트는 다음과 같습니다:

http://localhost:9000/mcp

Docker 배포

이미지 빌드

docker build -t searxng-mcp .

컨테이너 실행

docker run -d \
  --name searxng-mcp \
  -p 9000:9000 \
  -e SEARXNG_URL="https://searxng.abc.com" \
  searxng-mcp

포트를 변경하려면 컨테이너 내외부 포트와 PORT를 함께 덮어쓸 수 있습니다:

docker run -d \
  --name searxng-mcp \
  -p 8080:8080 \
  -e PORT=8080 \
  searxng-mcp

온라인 이미지 사용

docker run -d \
  --name searxng-mcp \
  -p 9000:9000 \
  -e SEARXNG_URL="https://searxng.abc.com" \
  muzihuaner/searxng-mcp:latest

접속 주소

배포 완료 후 MCP 엔드포인트 형식은 다음과 같습니다:

http://<你的服务器域名或IP>:<端口>/mcp

예: http://localhost:9000/mcp 또는 https://mcp.your-domain.com/mcp

클라이언트 구성

Streamable HTTP를 지원하는 MCP 클라이언트에서 서비스 주소를 위의 /mcp 엔드포인트로 입력하면 됩니다. 예:

{
  "mcpServers": {
    "searxng": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

도구 설명

search(query: str) -> str

키워드로 SearXNG 검색을 호출하고 각 결과 항목의 content 텍스트를 줄바꿈으로 연결하여 반환합니다.

• query: 검색 키워드.

• 반환: 검색 결과의 텍스트 내용; 요청 실패 시 False를 반환합니다.

동시성 및 성능

测试结果示例（局域网 / 上游 `so.xxx.cn`）：

총 요청 수 : 100 동시 worker : 50 성공 : 100 실패 : 0 총 소요 시간(초) : 67.68 처리량(QPS) : 1.48 평균 지연(초) : 27.284 최소 지연(초) : 7.203 최대 지연(초) : 44.418

> 注意：端到端延迟主要取决于 SearXNG 上游实例的响应速度（本例平均约 27s 来自上游 `so.xxx.cn` 较慢），服务本身可稳定承载并发且零失败。若需提升吞吐，可：
> - 换用响应更快 / 自托管的 SearXNG 实例（通过 `SEARXNG_URL` 指定）；

자주 묻는 질문

Q: 클라이언트에서 Missing session ID 오류가 발생합니까? A: 이 서비스는 stateless_http=True가 활성화되어 있어 세션이 필요 없습니다. 그래도 오류가 발생하면 클라이언트가 /mcp 엔드포인트를 가리키는지 확인하세요.

Q: 프로덕션 환경에서 CORS를 강화하려면 어떻게 하나요? A: Server.py의 CORSMiddleware에서 allow_origins=["*"]를 특정 출처 목록(예: ["https://your-domain.com"])으로 변경하세요.