serpent
serpent
MCP / AI 에이전트 워크플로우를 위해 구축된 오픈 소스 메타 검색 백엔드입니다.
여러 검색 엔진의 결과를 통합하고, 통일된 스키마를 반환하며, 표준 HTTP API와 LLM 에이전트가 직접 호출할 수 있는 MCP 서버를 모두 제공합니다.
이 프로젝트의 존재 이유
대부분의 검색 애그리게이터는 사람이 읽을 수 있는 출력(HTML 페이지, 결과 카드, 페이지네이션 UI)을 위해 설계되었습니다. LLM 에이전트가 웹을 검색해야 할 때는 구조화된 JSON, 안정적인 필드 이름, 동시 다중 소스 결과, 예측 가능한 오류 처리와 같은 다른 것이 필요합니다.
serpent는 이러한 사용 사례를 위해 설계되었습니다. SearXNG의 복제본이 아닙니다.
포지셔닝
에이전트 친화적인 메타 검색 백엔드
LLM 워크플로우를 위한 MCP 우선 검색 게이트웨이
AI 파이프라인을 위해 설계된 구조화된 검색 API
지원하는 제공자
Google은 직접 스크래핑하지 않습니다. 그 이유는 실용적입니다. Google의 봇 방지 조치로 인해 자체 호스팅 스크래핑은 취약합니다. 지속적으로 진화하는 Google의 탐지 기술에 대응하여 안정적인 스크래퍼를 유지하는 것은 끊임없는 고장과 높은 유지 관리 오버헤드를 의미합니다. 프로덕션 사용 사례에서는 타사 제공자가 더 안정적이고 비용 효율적입니다.
현재 지원되는 Google 제공자:
제공자 | 환경 변수 | 참고 |
| 사용량 기반 과금; 일반적으로 소량 사용 시 더 저렴 | |
| 2,500회 무료 쿼리 후 사용량 기반 과금 |
둘 다 저비용 옵션입니다. 캐주얼하거나 소량 사용 시에는 serpbase.dev가 쿼리당 더 저렴한 경향이 있습니다. 둘 다 작동하며, 선호하는 것을 구성하거나 둘 다 구성하여 대체용으로 사용할 수 있습니다.
웹 검색
제공자 | 이름 | 방식 | 인증 |
DuckDuckGo |
| HTML 스크래핑 (lite 엔드포인트) | 아니오 |
Bing |
| HTML 스크래핑 | 아니오 |
Yahoo |
| HTML 스크래핑 | 아니오 |
Brave |
| 공식 검색 API | 선택 사항 (무료 티어: 월 2000회) |
Ecosia |
| HTML 스크래핑 | 아니오 |
Mojeek |
| HTML 스크래핑 | 아니오 |
Startpage |
| HTML 스크래핑 (최선 노력) | 아니오 |
Qwant |
| 내부 JSON API (최선 노력) | 아니오 |
Yandex |
| HTML 스크래핑 (최선 노력) | 아니오 |
Baidu |
| HTML 스크래핑 (최선 노력) | 아니오 |
**최선 노력(best-effort)**으로 표시된 제공자는 문서화되지 않은 엔드포인트나 강력한 봇 방지 조치가 적용된 스크래핑 대상을 사용합니다. 예고 없이 작동이 중단될 수 있습니다.
지식 / 참조
제공자 | 이름 | 방식 | 인증 |
Wikipedia |
| MediaWiki Action API | 아니오 |
Wikidata |
| Wikidata API (엔티티 검색) | 아니오 |
Internet Archive |
| 고급 검색 API | 아니오 |
개발자
제공자 | 이름 | 방식 | 인증 |
GitHub |
| GitHub REST API | 아니오 (토큰 사용 시 제한 상향) |
Stack Overflow |
| Stack Exchange API | 아니오 (키 사용 시 제한 상향) |
Hacker News |
| Algolia HN API | 아니오 |
| 공개 JSON API | 아니오 | |
npm |
| npm 레지스트리 API | 아니오 |
PyPI |
| HTML 스크래핑 | 아니오 |
crates.io |
| crates.io REST API | 아니오 |
학술
제공자 | 이름 | 방식 | 인증 |
arXiv |
| Atom API | 아니오 |
PubMed |
| NCBI E-utilities | 아니오 (키 사용 시 제한 상향) |
Semantic Scholar |
| Graph API | 아니오 (키 사용 시 제한 상향) |
CrossRef |
| REST API (1억 4500만 개 이상의 DOI) | 아니오 |
설치
# Clone the repository
git clone https://github.com/your-org/serpent
cd serpent
# Install with pip (editable)
pip install -e ".[dev]"
# Or with uv
uv pip install -e ".[dev]"구성
.env.example을 .env로 복사하고 키를 입력하세요:
cp .env.example .env# Required for Google search (at least one)
SERPBASE_API_KEY=your_key_here
SERPER_API_KEY=your_key_here
# Optional — omit to use unauthenticated/public access
BRAVE_API_KEY= # free tier: 2000 req/month
GITHUB_TOKEN= # raises rate limit from 60 to 5000 req/hour
STACKEXCHANGE_API_KEY= # raises limit from 300 to 10,000 req/day
NCBI_API_KEY= # PubMed; raises from 3 to 10 req/sec
SEMANTIC_SCHOLAR_API_KEY= # raises from 1 to 10 req/sec
# Server
HOST=0.0.0.0
PORT=8000
# Restrict which providers are active (comma-separated, empty = all available)
ENABLED_PROVIDERS=
ALLOW_UNSTABLE_PROVIDERS=false
# Timeouts in seconds
DEFAULT_TIMEOUT=10
AGGREGATOR_TIMEOUT=15
MAX_RESULTS_PER_PROVIDER=10실행
HTTP API 서버
python -m serpent.main
# or
serpent서버는 http://localhost:8000에서 시작됩니다. 대화형 문서는 /docs에서 확인할 수 있습니다.
MCP 서버
python -m serpent.mcp_server
# or
serpent-mcpMCP 서버는 stdio를 통해 통신합니다. MCP 호환 클라이언트(Claude Desktop, cline, continue.dev 등)와 함께 사용하세요.
Docker
이미지 빌드:
docker build -t serpent .HTTP API 실행:
docker run --rm -p 8000:8000 --env-file .env serpent또는 Docker Compose 사용:
docker compose up --build컨테이너는 http://localhost:8000에서 HTTP API를 시작합니다.
HTTP API
POST /search
활성화된 모든 제공자에 걸쳐 검색을 통합합니다.
curl -X POST http://localhost:8000/search \
-H "Content-Type: application/json" \
-d '{"query": "rust async runtime"}'명시적 제공자 및 매개변수 사용:
curl -X POST http://localhost:8000/search \
-H "Content-Type: application/json" \
-d '{
"query": "rust async runtime",
"providers": ["duckduckgo", "wikipedia"],
"params": {"num_results": 5, "language": "en"}
}'응답:
{
"engine": "serpent",
"query": "rust async runtime",
"results": [
{
"title": "Tokio - An asynchronous Rust runtime",
"url": "https://tokio.rs",
"snippet": "Tokio is an event-driven, non-blocking I/O platform...",
"source": "tokio.rs",
"rank": 1,
"provider": "duckduckgo",
"published_date": null,
"extra": {}
}
],
"related_searches": ["tokio vs async-std", "rust futures"],
"suggestions": [],
"answer_box": null,
"timing_ms": 843.2,
"providers": [
{"name": "duckduckgo", "success": true, "result_count": 10, "latency_ms": 840.1, "error": null},
{"name": "wikipedia", "success": true, "result_count": 3, "latency_ms": 320.5, "error": null}
],
"errors": []
}POST /search/google
curl -X POST http://localhost:8000/search/google \
-H "Content-Type: application/json" \
-d '{"query": "site:github.com rust tokio"}'GET /health
curl http://localhost:8000/health
# {"status": "ok"}GET /providers
curl http://localhost:8000/providers{
"available": [
{"name": "google_serpbase", "tags": ["google", "web"]},
{"name": "duckduckgo", "tags": ["web", "privacy"]},
{"name": "wikipedia", "tags": ["web", "academic", "knowledge"]},
{"name": "github", "tags": ["code", "web"]},
{"name": "arxiv", "tags": ["academic", "web"]}
],
"count": 5
}MCP 사용법
MCP 클라이언트가 serpent-mcp(또는 python -m serpent.mcp_server)를 실행하도록 구성하세요.
Claude Desktop 구성 예시 (~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"serpent": {
"command": "serpent-mcp",
"env": {
"SERPBASE_API_KEY": "your_key",
"SERPER_API_KEY": "your_key"
}
}
}
}사용 가능한 MCP 도구
search_web
활성화된 모든 제공자에 대한 일반 웹 검색.
{
"query": "fastapi vs flask performance 2024",
"num_results": 10
}search_google
구성된 타사 제공자를 통한 Google 검색.
{
"query": "site:docs.python.org asyncio",
"provider": "google_serpbase"
}search_academic
arXiv 및 Wikipedia 검색.
{
"query": "transformer architecture attention mechanism",
"num_results": 8
}search_github
GitHub 저장소 검색.
{
"query": "python mcp server implementation",
"num_results": 5
}compare_engines
여러 제공자에 걸쳐 동일한 쿼리를 실행하고 엔진별로 그룹화된 결과를 반환합니다.
{
"query": "vector database comparison",
"providers": ["duckduckgo", "brave"],
"num_results": 5
}결과 스키마 참조
모든 결과 객체는 다음 필드를 가집니다:
필드 | 타입 | 설명 | |
| string | 결과 제목 | |
| string | 결과 URL | |
| string | 텍스트 발췌 / 설명 | |
| string | 도메인 이름 | |
| int | 최종 병합된 목록에서의 1부터 시작하는 위치 | |
| string | 이 결과를 반환한 제공자 | |
| string | null | ISO 날짜 (YYYY-MM-DD), 가능한 경우 |
| object | 제공자별 데이터 (예: GitHub 별점, arXiv 저자) |
개발
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run with auto-reload
uvicorn serpent.main:app --reload로드맵
[ ] 반복 쿼리를 위한 캐싱 계층 (인메모리 / Redis)
[ ] 제공자 간 관련성 재순위 지정
[ ] 추가 제공자: Bing (공식 API), Kagi, Tavily
[ ] 백오프를 포함한 제공자별 속도 제한
[ ] 긴 통합 작업을 위한 스트리밍 응답 (SSE)
[ ] Docker 이미지 및 Compose 설정
[ ] 제공자 상태 모니터링 엔드포인트
[ ] 결과 점수 매기기 및 신뢰도 신호
라이선스
MIT
Available Tools
5 toolscompare_enginesA
Run the same query against multiple providers and return results grouped by provider for side-by-side comparison.
Inputs: query (required), providers, num_results.
search_academicB
Search academic sources (arXiv, Wikipedia). Best for research questions, paper discovery, and factual lookups.
Inputs: query (required), num_results.
search_githubC
Search GitHub repositories. Returns repo name, description, stars, language, and topics.
Inputs: query (required), num_results.
search_googleA
Search Google via a configured third-party provider (serpbase or serper). Returns structured organic results, answer boxes, and related searches.
Inputs: query (required), provider, num_results.
search_webB
Search the web using all enabled providers and return aggregated, deduplicated results with a unified schema. Good for general queries.
Inputs: query (required), providers, num_results, language, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The tools are mostly distinct, with each targeting a specific search domain (academic, GitHub, Google, web) or a comparison function. However, 'search_web' and 'search_google' could be confused, as Google is a web search provider, but the descriptions clarify that 'search_web' aggregates multiple providers while 'search_google' is specific to Google. This minor overlap is mitigated by clear descriptions.
All tool names follow a consistent verb_noun pattern with snake_case, using 'search_' for four tools and 'compare_' for one. The naming is predictable and readable, with no deviations in style or convention, making it easy for agents to understand and use the tool set.
With 5 tools, the set is well-scoped for a search-focused server. Each tool serves a clear purpose (e.g., different search types and a comparison feature), and there are no extraneous tools. The count is appropriate, allowing coverage of key search domains without being overwhelming.
The tool set covers major search domains (academic, GitHub, Google, general web) and includes a useful comparison tool. Minor gaps exist, such as no tools for filtering or refining search results (e.g., by date or language), but agents can work around this with the provided tools. The surface is largely complete for a search-oriented server.
Related MCP Connectors
Web search API and MCP server for developers building AI agents.
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Your agent needs the open web — searched by more than one engine, and read as clean markdown rather than raw HTML. **What you can ask for** • "Search this question with two providers and tell me where they disagree." • "Scrape these 40 URLs into markdown, in one batch." • "Crawl this documentation site and give me every page." • "Do deep research on this topic and cite the sources." • "Find the academic papers behind this claim." **How to use it** Point any MCP client at https://mcp.aisa.one/search/mcp and sign in with OAuth — there is no key to create or paste. 30 tools across several independent providers: Tavily and Exa search, answers, contents and agent runs; Firecrawl scrape, batch scrape, crawl, map and search; Perplexity Sonar, Sonar Pro, reasoning and deep research; Oxylabs AI search and LLM jobs; OpenAI and Anthropic web search; and scholarly search. **Why this rather than the source** Several independent indexes behind one account, because one engine's blind spot is not visible from inside it. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the page here, then ask the same agent who links to it or how much traffic it gets — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/seo-serp/mcp for the Google results page itself, https://mcp.aisa.one/seo-serp-other-engines/mcp for Bing, Baidu and Naver.
Multi-engine search for AI agents. Trust scoring, local corpus, MCP-native. Self-hostable, BYOK.