Skip to main content
Glama

serpent

MCP / AIエージェントワークフロー向けに構築されたオープンソースのメタ検索バックエンド。

複数の検索エンジンから結果を集約し、統一されたスキーマを返し、LLMエージェントが直接呼び出せる標準HTTP APIとMCPサーバーの両方を提供します。


なぜこれが必要なのか

ほとんどの検索アグリゲーターは、HTMLページ、結果カード、ページネーションUIなど、人間が読むための出力用に設計されています。LLMエージェントがウェブ検索を行う際には、構造化されたJSON、安定したフィールド名、複数のソースからの同時結果取得、予測可能なエラー処理など、異なるものが必要となります。

serpentはそのようなユースケースのために設計されています。SearXNGのクローンではありません。

ポジショニング

  • エージェントフレンドリーなメタ検索バックエンド

  • LLMワークフローのためのMCPファーストな検索ゲートウェイ

  • AIパイプライン向けに設計された構造化検索API


サポートされているプロバイダー

Google

Googleは直接スクレイピングされません。理由は実用的です。Googleのボット対策により、自己ホスト型のスクレイピングは脆弱になるためです。Googleの絶えず進化する検知機能に対して信頼性の高いスクレイパーを維持することは、絶え間ない故障と高いメンテナンスコストを意味します。本番環境でのユースケースでは、サードパーティプロバイダーの方が信頼性が高く、費用対効果に優れています。

現在サポートされているGoogleプロバイダー:

プロバイダー

環境変数

備考

serpbase.dev

SERPBASE_API_KEY

従量課金制。低ボリュームでは一般的に安価

serper.dev

SERPER_API_KEY

2,500クエリまで無料、以降は従量課金制

どちらも低コストなオプションです。カジュアルまたは低ボリュームでの使用には、serpbase.devの方がクエリあたりの単価が安くなる傾向があります。どちらでも動作します。好みのものを設定するか、フォールバック用に両方を設定してください。

ウェブ検索

プロバイダー

名前

メソッド

認証

DuckDuckGo

duckduckgo

HTMLスクレイピング (liteエンドポイント)

なし

Bing

bing

HTMLスクレイピング

なし

Yahoo

yahoo

HTMLスクレイピング

なし

Brave

brave

公式検索API

オプション (無料枠: 月2000回)

Ecosia

ecosia

HTMLスクレイピング

なし

Mojeek

mojeek

HTMLスクレイピング

なし

Startpage

startpage

HTMLスクレイピング (ベストエフォート)

なし

Qwant

qwant

内部JSON API (ベストエフォート)

なし

Yandex

yandex

HTMLスクレイピング (ベストエフォート)

なし

Baidu

baidu

HTMLスクレイピング (ベストエフォート)

なし

ベストエフォートと記載されたプロバイダーは、非公開のエンドポイントや強力なボット対策が施されたスクレイピング対象を使用しています。予告なく動作しなくなる可能性があります。

知識 / リファレンス

プロバイダー

名前

メソッド

認証

Wikipedia

wikipedia

MediaWiki Action API

なし

Wikidata

wikidata

Wikidata API (エンティティ検索)

なし

Internet Archive

internet_archive

高度な検索API

なし

開発者

プロバイダー

名前

メソッド

認証

GitHub

github

GitHub REST API

なし (トークンでレート制限緩和)

Stack Overflow

stackoverflow

Stack Exchange API

なし (キーで制限緩和)

Hacker News

hackernews

Algolia HN API

なし

Reddit

reddit

公開JSON API

なし

npm

npm

npmレジストリAPI

なし

PyPI

pypi

HTMLスクレイピング

なし

crates.io

crates

crates.io REST API

なし

学術

プロバイダー

名前

メソッド

認証

arXiv

arxiv

Atom API

なし

PubMed

pubmed

NCBI E-utilities

なし (キーでレート制限緩和)

Semantic Scholar

semanticscholar

Graph API

なし (キーでレート制限緩和)

CrossRef

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-mcp

MCPサーバーは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
}

結果スキーマのリファレンス

すべての結果オブジェクトには以下のフィールドが含まれます:

フィールド

型

説明

title

string

結果のタイトル

url

string

結果のURL

snippet

string

テキストの抜粋 / 説明

source

string

ドメイン名

rank

int

最終的なマージリスト内での1から始まる順位

provider

string

この結果を返したプロバイダー

published_date

string

null

ISO日付 (YYYY-MM-DD)、利用可能な場合

extra

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