Skip to main content
Glama

serpent

Ein Open-Source-Metasuch-Backend, das für MCP- / KI-Agenten-Workflows entwickelt wurde.

Es aggregiert Ergebnisse von mehreren Suchmaschinen, gibt ein einheitliches Schema zurück und stellt sowohl eine Standard-HTTP-API als auch einen MCP-Server bereit, den LLM-Agenten direkt aufrufen können.


Warum existiert dies?

Die meisten Suchaggregatoren sind für menschenlesbare Ausgaben konzipiert: HTML-Seiten, Ergebniskarten, Paginierungs-UIs. Wenn ein LLM-Agent das Web durchsuchen muss, benötigt er etwas anderes: strukturiertes JSON, stabile Feldnamen, gleichzeitige Ergebnisse aus mehreren Quellen und eine vorhersehbare Fehlerbehandlung.

serpent ist für diesen Anwendungsfall konzipiert. Es ist kein SearXNG-Klon.

Positionierung

  • Agentenfreundliches Metasuch-Backend

  • MCP-First-Such-Gateway für LLM-Workflows

  • Strukturierte Such-API für KI-Pipelines


Unterstützte Anbieter

Google

Google wird nicht direkt gescrapt. Der Grund ist praktisch: Googles Anti-Bot-Maßnahmen machen selbst gehostetes Scraping anfällig. Die Aufrechterhaltung eines zuverlässigen Scrapers gegen Googles sich ständig weiterentwickelnde Erkennung bedeutet ständige Ausfälle und einen hohen Wartungsaufwand. Für Produktionsanwendungsfälle sind Drittanbieter zuverlässiger und kostengünstiger.

Derzeit unterstützte Google-Anbieter:

Anbieter

Umgebungsvariable

Hinweise

serpbase.dev

SERPBASE_API_KEY

Pay-per-Use; generell günstiger bei geringem Volumen

serper.dev

SERPER_API_KEY

2.500 kostenlose Abfragen, danach Pay-per-Use

Beide sind kostengünstige Optionen. Für gelegentliche oder geringe Nutzung ist serpbase.dev pro Abfrage tendenziell günstiger. Beide funktionieren; konfigurieren Sie, was Sie bevorzugen, oder beide als Fallback.

Websuche

Anbieter

Name

Methode

Authentifizierung

DuckDuckGo

duckduckgo

HTML-Scraping (Lite-Endpunkt)

Nein

Bing

bing

HTML-Scraping

Nein

Yahoo

yahoo

HTML-Scraping

Nein

Brave

brave

Offizielle Such-API

Optional (kostenlose Stufe: 2000/Monat)

Ecosia

ecosia

HTML-Scraping

Nein

Mojeek

mojeek

HTML-Scraping

Nein

Startpage

startpage

HTML-Scraping (Best-Effort)

Nein

Qwant

qwant

Interne JSON-API (Best-Effort)

Nein

Yandex

yandex

HTML-Scraping (Best-Effort)

Nein

Baidu

baidu

HTML-Scraping (Best-Effort)

Nein

Anbieter, die als Best-Effort gekennzeichnet sind, verwenden undokumentierte Endpunkte oder Scraping-Ziele mit starken Anti-Bot-Maßnahmen. Sie können ohne Vorwarnung aufhören zu funktionieren.

Wissen / Referenz

Anbieter

Name

Methode

Authentifizierung

Wikipedia

wikipedia

MediaWiki Action API

Nein

Wikidata

wikidata

Wikidata API (Entitätssuche)

Nein

Internet Archive

internet_archive

Advanced Search API

Nein

Entwickler

Anbieter

Name

Methode

Authentifizierung

GitHub

github

GitHub REST API

Nein (Token erhöht Ratenlimit)

Stack Overflow

stackoverflow

Stack Exchange API

Nein (Schlüssel erhöht Limit)

Hacker News

hackernews

Algolia HN API

Nein

Reddit

reddit

Öffentliche JSON-API

Nein

npm

npm

npm Registry API

Nein

PyPI

pypi

HTML-Scraping

Nein

crates.io

crates

crates.io REST API

Nein

Akademisch

Anbieter

Name

Methode

Authentifizierung

arXiv

arxiv

Atom API

Nein

PubMed

pubmed

NCBI E-utilities

Nein (Schlüssel erhöht Ratenlimit)

Semantic Scholar

semanticscholar

Graph API

Nein (Schlüssel erhöht Ratenlimit)

CrossRef

crossref

REST API (145M+ DOIs)

Nein


Installation

# 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]"

Konfiguration

Kopieren Sie .env.example nach .env und tragen Sie Ihre Schlüssel ein:

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

Ausführung

HTTP-API-Server

python -m serpent.main
# or
serpent

Der Server startet unter http://localhost:8000. Interaktive Dokumentation unter /docs.

MCP-Server

python -m serpent.mcp_server
# or
serpent-mcp

Der MCP-Server kommuniziert über stdio. Verwenden Sie ihn mit jedem MCP-kompatiblen Client (Claude Desktop, cline, continue.dev, etc.).

Docker

Bauen Sie das Image:

docker build -t serpent .

Führen Sie die HTTP-API aus:

docker run --rm -p 8000:8000 --env-file .env serpent

Oder mit Docker Compose:

docker compose up --build

Der Container startet die HTTP-API unter http://localhost:8000.


HTTP-API

POST /search

Aggregiert die Suche über alle aktivierten Anbieter.

curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async runtime"}'

Mit expliziten Anbietern und Parametern:

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"}
  }'

Antwort:

{
  "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-Nutzung

Konfigurieren Sie Ihren MCP-Client so, dass er serpent-mcp (oder python -m serpent.mcp_server) ausführt.

Beispiel für die Claude Desktop-Konfiguration (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "serpent": {
      "command": "serpent-mcp",
      "env": {
        "SERPBASE_API_KEY": "your_key",
        "SERPER_API_KEY": "your_key"
      }
    }
  }
}

Verfügbare MCP-Tools

search_web

Allgemeine Websuche über alle aktivierten Anbieter.

{
  "query": "fastapi vs flask performance 2024",
  "num_results": 10
}

search_google

Google-Suche über einen konfigurierten Drittanbieter.

{
  "query": "site:docs.python.org asyncio",
  "provider": "google_serpbase"
}

search_academic

Suche in arXiv und Wikipedia.

{
  "query": "transformer architecture attention mechanism",
  "num_results": 8
}

search_github

Suche in GitHub-Repositories.

{
  "query": "python mcp server implementation",
  "num_results": 5
}

compare_engines

Führen Sie dieselbe Abfrage über mehrere Anbieter aus und geben Sie die nach Engine gruppierten Ergebnisse zurück.

{
  "query": "vector database comparison",
  "providers": ["duckduckgo", "brave"],
  "num_results": 5
}

Referenz des Ergebnisschemas

Jedes Ergebnisobjekt hat diese Felder:

Feld

Typ

Beschreibung

title

string

Ergebnistitel

url

string

Ergebnis-URL

snippet

string

Textauszug / Beschreibung

source

string

Domainname

rank

int

1-basierte Position in der endgültigen zusammengeführten Liste

provider

string

Anbieter, der dieses Ergebnis zurückgegeben hat

published_date

string

null

ISO-Datum (JJJJ-MM-TT), falls verfügbar

extra

object

Anbieterspezifische Daten (z. B. GitHub-Sterne, arXiv-Autoren)


Entwicklung

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with auto-reload
uvicorn serpent.main:app --reload

Roadmap

  • [ ] Caching-Schicht (In-Memory / Redis) für wiederholte Abfragen

  • [ ] Relevanz-Neubewertung über Anbieter hinweg

  • [ ] Weitere Anbieter: Bing (offizielle API), Kagi, Tavily

  • [ ] Ratenbegrenzung pro Anbieter mit Backoff

  • [ ] Streaming-Antworten (SSE) für lange Aggregationen

  • [ ] Docker-Image und Compose-Setup

  • [ ] Endpunkt zur Überwachung des Anbieterstatus

  • [ ] Ergebnis-Scoring und Konfidenzsignale


Lizenz

MIT

Available Tools

5 tools
compare_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

    A3.6/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

      https://searchpipe.tech/mcp/
    • One MCP server for all web data. Scrape, search, crawl, and AI research in one install.

      https://mcp.novada.com/mcp
    • 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.

      https://qsearch.pro/mcp