OpenSERP

@openserp/mcp

6つの検索エンジン（Google、Bing、Yandex、Baidu、DuckDuckGo、Ecosia）でのリアルタイム検索、画像検索、AI エージェント向けの単一ページ／一括ページ抽出に対応します。結果には元の検索エンジンと順位が保持されます。セルフホスト可能な OpenSERP サーバー、またはOpenSERP Cloudで動作します。

OPENSERP_API_KEYが設定されていない場合、サーバーはhttp://localhost:7000でOSSモードを使用し、次の内容を書き込みます。

[openserp-mcp] No OPENSERP_API_KEY set - using OSS mode at http://localhost:7000.
[openserp-mcp] Get an API key: https://openserp.org/dashboard/keys
[openserp-mcp] Docs: https://openserp.org/docs | Issues: https://github.com/openserpapi/mcp/issues

OpenSERP Cloudを使用するには、OPENSERP_API_KEYを設定してください。APIキーはhttps://openserp.org/dashboard/keysで取得できます。別の互換性のあるOpenSERP APIベースURLを指定するには、OPENSERP_BASE_URLを設定してください。

インストール

npm install -g @openserp/mcp

インストールせずに実行することもできます。

npx -y @openserp/mcp --stdio

ツール

ツール	使用する場面
search	検索エンジンが重要な場合（ロシア語ならYandex、中国語ならBaidu）、またはstartでページ指定する場合
any_search	優先する検索エンジンを指定し、指定した順序でフォールバックさせたい場合
fast_search	どの検索エンジンでもよい場合。最も健全で高速なものを選択します
mega_search	検索エンジンを比較したい、または広範囲に検索したい場合。結果には検索エンジンと順位が保持されます
image_search	1つの検索エンジンから画像を検索する場合
mega_image	複数の検索エンジンの画像を統合する場合
extract	1つのページをMarkdownとして読み取る場合
batch_extract	複数のページを1回の呼び出しで読み取る場合（最大20件）。失敗したURLがあってもバッチ全体は失敗しません
list_engines	検索に繰り返し失敗し、利用可能な検索エンジンを確認したい場合
get_usage	Cloudのクレジット残高や直近の呼び出し料金を確認する場合

extractとbatch_extractは、エージェントのコンテキストに収まるよう長いページを切り詰めます。ページごとに20,000文字、バッチ全体で40,000文字（URLごとに最低2,000文字）です。切り詰められた内容の末尾には[truncated: ...]行が付き、truncated／metadata.truncatedで示されます。さらに読み込むにはmaxCharsを指定してください。

使用例

MCPクライアントに次のように依頼できます。

• Googleで最新のドキュメントを検索し、上位5件のURLを返す。
• SEOキーワードについてGoogleとBingの検索結果を比較する。
• LLMに渡す前に、URLから整形済みのMarkdownを抽出する。
• batch_extractを使い、複数のソースを一度に参照して回答を裏付ける。1回の往復で最大20件のURLを処理でき、リンク切れはバッチ全体を失敗させず、エラー項目として返されます。
• region: "DE"を指定して、ジオフェンスされたページを現地の訪問者として読み取る。
• get_usageで残りのCloudクレジットを確認する。

Cloud検索パラメーター

Cloudへのリクエストでは、OPENSERP_API_KEYを使ってAuthorization: Bearerを指定します。ページ送りにはstartを使用し、limit: 10を維持してください。has_moreがtrueの場合、前回のレスポンスのpagination.next_startを渡します。Google、Bing、Yandexでは10の倍数を指定します。Baiduは初期ページ、Ecosiaは任意のオフセットに対応し、DuckDuckGoは最初のページのみ対応します。mode: "balanced"を指定したmega_searchではstart > 0が拒否されます。後続ページにはsearch、any_search、またはfast_searchを使用してください。

Cloudのウェブ検索では、GoogleとEcosiaでdate: "20250101..20251231"をサポートしています。サポートされていないオフセットや日付フィルターを指定すると、課金されずに400 invalid_requestが返されます。再試行する前にリクエストを修正してください。

list_enginesはCloudの機能に加えて、運用状況を示すstatusを返します。デフォルトを使用するにはenginesを省略してください。Anyは指定した順序で検索エンジンを起動し、低速な試行を並行して実行します。Fastは直近の健全性とレイテンシーを優先します。勝者はmeta.engine_usedで確認できます。engines_triedとengines_skippedは含まれない場合があります。

ツールのエラーには、公開HTTPステータス、エラーコード、リクエストID、および存在する場合は再試行までの遅延が含まれます。429と503ではretry_afterに従ってください。503 engine_unavailableには60秒の遅延が設定されています。サーバーは自動的に再試行しません。

Claude Desktop

ローカルOSSモード：

{
  "mcpServers": {
    "openserp": {
      "command": "npx",
      "args": ["-y", "@openserp/mcp"]
    }
  }
}

Cloudモード：

{
  "mcpServers": {
    "openserp": {
      "command": "npx",
      "args": ["-y", "@openserp/mcp"],
      "env": {
        "OPENSERP_API_KEY": "osk_live_..."
      }
    }
  }
}

Cursor

stdioを使用する場合は、MCPサーバーのエントリーを追加します。

{
  "mcpServers": {
    "openserp": {
      "command": "npx",
      "args": ["-y", "@openserp/mcp"],
      "env": {
        "OPENSERP_API_KEY": "osk_live_..."
      }
    }
  }
}

リモート形式のHTTPを使用する場合は、次を実行します。

npx -y @openserp/mcp --http --host 127.0.0.1 --port 3333

次に、ストリーミング可能なHTTP MCPクライアントを次のエンドポイントに接続します。

http://127.0.0.1:3333/mcp

古いSSEトランスポートを引き続き使用するクライアントは、次のエンドポイントに接続できます。

http://127.0.0.1:3333/sse

環境

• OPENSERP_API_KEY：https://openserp.org/dashboard/keys から取得するクラウド API キーです。
• OPENSERP_BASE_URL：API ベース URL の上書き設定です。
• OPENSERP_BACKEND：任意のバックエンド指定です。oss または cloud を指定します。
• OPENSERP_TIMEOUT_MS：SDK リクエストのタイムアウト時間（ミリ秒）です。
• HOST：HTTP ホストです。デフォルトは 127.0.0.1 です。
• PORT：HTTP ポートです。デフォルトは 3333 です。

リソース

• OpenSERP Cloud のドキュメント
• MCP サーバーのソースコード
• JavaScript SDK