mcp-serp

SerpMCP

AceDataCloud APIを通じてSERP APIを使用する、Google 検索用のModel Context Protocol（MCP）サーバーです。

Claude、VS Code、またはその他の MCP 互換クライアントから Google 検索を実行し、構造化された結果を直接取得できます。

機能

• ウェブ検索 - 構造化された結果を取得できる通常の Google ウェブ検索
• 画像検索 - URL とサムネイル付きの画像を検索
• ニュース検索 - あらゆるトピックの最新ニュース記事を取得
• 動画検索 - YouTube などのソースから動画を検索
• 場所検索 - 地元の事業者や場所を検索
• マップ検索 - 場所や地理情報を検索
• ナレッジグラフ - 構造化されたエンティティ情報を取得
• ローカライズ - 複数の国と言語に対応
• 時間フィルター - 時間範囲で結果を絞り込み

ツールリファレンス

ツール	説明
serp_google_search	SERP API を使用して Google を検索し、構造化された結果を取得します。
serp_google_images	Google 画像検索を行い、画像の結果を取得します。
serp_google_news	Google ニュースを検索し、ニュース記事の結果を取得します。
serp_google_videos	Google 動画検索を行い、動画の結果を取得します。
serp_google_places	Google で地元の場所や事業者を検索します。
serp_google_maps	Google マップで場所を検索します。
serp_list_search_types	利用可能な Google 検索タイプをすべて一覧表示します。
serp_list_countries	Google 検索でよく使われる国コードを一覧表示します。
serp_list_languages	Google 検索でよく使われる言語コードを一覧表示します。
serp_list_time_ranges	Google 検索で利用可能な時間範囲フィルターを一覧表示します。
serp_get_usage_guide	Google SERP ツールの使用方法を詳しく説明したガイドを取得します。

接続：ホスト型 OAuth、API トークン、またはローカル stdio

ホスト型エンドポイントは https://serp.mcp.acedata.cloud/mcp です。MCP クライアントで、次のいずれかの方法を選択してください。

方法	使用する場面	認証情報の設定
ホスト型 OAuth	クライアントがリモート MCP OAuth に対応している場合	URL のみを追加し、AceDataCloud にサインインしてアクセスを承認します。クライアント設定にトークンを貼り付ける必要はありません。
ホスト型 API トークン	クライアントで OAuth を完了できない場合、または明示的な連携用認証情報が必要な場合	Authorization: Bearer … ヘッダーで AceDataCloud API トークンを送信します。ローカルのシークレットストアまたは環境変数に保管してください。
ローカル stdio	クライアントがローカル MCP プロセスを実行する場合	mcp-serp をインストールし、ACEDATACLOUD_API_TOKEN をそのプロセスに渡します。引き続き AceDataCloud API を呼び出します。

ホスト型サービスは、OAuth メタデータと Dynamic Client Registration（DCR）を提供します。DCR はクライアントアプリケーションを登録するもので、API キーではありません。 OAuth でサインインすると、クライアントは取得した Bearer トークンを送信します。アカウントの API 認証情報を再利用する場合も、新たに作成する場合もあります。ブラウザーでサインインするには、引き続き AceDataCloud アカウントが必要です。ホスト型サービスは従量課金制の場合があります。実際に操作する前に、最新のサービスドキュメントと表示される料金を確認してください。同じサーバーに OAuth ログインと固定の Authorization ヘッダーを両方設定しないでください。

ホスト型 OAuth の例

• Claude と Claude Desktop のチャット： Customize → Connectors → Add custom connector からリモートのカスタムコネクターを追加し、https://serp.mcp.acedata.cloud/mcp を入力してサインインを選択します。Claude から OAuth クライアントの登録方法を尋ねられた場合は、Register automatically を選択してください。同意手続きを完了します。Claude Desktop のローカル claude_desktop_config.json は別途設定します。Claude コネクターガイド。
• Claude Code： claude mcp add --transport http --scope user serp https://serp.mcp.acedata.cloud/mcp を実行し、次に claude を起動して /mcp を開き、Serp サーバーを認証します。Claude Code MCP ガイド。
• Cursor： https://serp.mcp.acedata.cloud/mcp のみを指定してリモートサーバーを追加します。プロジェクトで使う場合は、以下のエントリーを <project>/.cursor/mcp.json にマージします。個人用の場合は、~/.cursor/mcp.json を使用します。Cursor MCP ガイド。
• VS Code / Copilot： MCP: Add Server を実行し、HTTP を選択して https://serp.mcp.acedata.cloud/mcp を入力し、ブラウザーでのサインインを完了します。新しいポータブルなワークスペース設定には <project>/.mcp.json を使用します。以下の VS Code 固有の形式では、<project>/.vscode/mcp.json またはユーザープロファイルを使用します。MCP: List Servers を確認してください。VS Code MCP の設定。
• Codex： codex mcp add serp --url https://serp.mcp.acedata.cloud/mcp を実行し、次に codex mcp login serp を実行します。ユーザー設定は ~/.codex/config.toml にあります。Codex 公式 MCP ガイド。

Cursor のプロジェクト設定（OAuth）：

{
  "mcpServers": {
    "serp": {"url": "https://serp.mcp.acedata.cloud/mcp"}
  }
}

VS Code 固有のワークスペース設定（OAuth）：

{
  "servers": {
    "serp": {"type": "http", "url": "https://serp.mcp.acedata.cloud/mcp"}
  }
}

ホスト型 API トークン

1. Ace Data Cloud → Applications を開きます。サインインするか、先にアカウントを登録します。
2. General application を探します。作成されていない場合は、Initialize General Application を選択します。汎用キーではアカウントで利用可能なサービスを使用できますが、専用アプリケーションのキーはそのサービスに限定されます。必要なサービス／モデルへのアクセス権と現在の料金を確認します。
3. アプリケーションカードから API Key をコピーするか、Keys / Manage Keys → Create を開き、この連携用に別のキーを作成します。独立して失効またはローテーションできるよう、見分けやすい名前を付けます。
4. キーを作成する際は、Expiration Time、Set Usage Limitation、Allowed APIs を確認します。必要な制限だけを有効にし、使用する操作を許可してから、Create をクリックし、キーの一覧からトークンをコピーします。タスクの照会権限があっても、生成を送信する権限が付与されるわけではありません。最初のリクエストに必要な残高がアプリケーションにあることを確認します。試用枠がある場合は、現在アカウントに表示されている内容に従います。
5. 引用符、スペース、Bearer を含めず、トークンの値だけをコピーします。API Key / API Token フィールドにはこの生の値を入力します。手動で HTTP Authorization ヘッダーを設定する場合に限り、Bearer プレフィックスが必要です。platform-... 形式のアカウント管理トークンを、生成 API キーの代わりに使用することはできません。

キーはクライアントの認証情報ストア、または以下に示す環境変数に保存します。プロンプト、共有ワークフロー、スクリーンショット、Git のコミットには絶対に含めないでください。認証に失敗した場合は、別のキーを作成する前に、コピーした値全体、アプリケーション／サービスへのアクセス権、有効期限、利用制限、残高を確認します。

固定の Bearer ヘッダーは OAuth を迂回します。ヘッダーが無効な場合は、ブラウザーでのサインインを試す前に削除してください。保存した認証情報は非公開にしてください。

Claude Code では、サーバーを追加するときにシェルがトークンを展開します。保存したユーザー MCP 設定は秘密情報として扱ってください。

export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
claude mcp add --transport http --scope user serp https://serp.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer $ACEDATACLOUD_API_TOKEN"

Claude Code のプロジェクト設定では、<project>/.mcp.json に変数参照を記述し、Claude Code を起動する環境でその変数を設定します。

{
  "mcpServers": {
    "serp": {
      "type": "http",
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

Cursor では、~/.cursor/mcp.json またはコミットしないプロジェクト設定で、異なる環境変数構文を使用します。

{
  "mcpServers": {
    "serp": {
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${env:ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

VS Code では、MCP: Open User Configuration を実行し、このサーバーとマスクされた入力をマージします。${input:...} は VS Code のユーザー／ワークスペース形式用であり、Agent Host の .mcp.json 形式には移植できません。

{
  "inputs": [
    {"id": "acedata-serp-token", "type": "promptString", "description": "AceDataCloud API token", "password": true}
  ],
  "servers": {
    "serp": {
      "type": "http",
      "url": "https://serp.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${input:acedata-serp-token}"}
    }
  }
}

Cline では、MCP 設定 UI または CLI ファイル ~/.cline/data/settings/cline_mcp_settings.json を使用します。リモートトランスポートの値は streamableHttp です。JetBrains AI Assistant では、Settings → Tools → AI Assistant → Model Context Protocol (MCP) からリモート URL を追加します。Zed では、OAuth の場合は URL のみを指定した context_servers エントリーを使用するか、ローカルの Bearer ヘッダーを追加します。これらのクライアントでは設定スキーマがそれぞれ異なります。他のクライアントの JSON をコピーせず、各クライアントの最新の UI に従ってください。Cline · JetBrains · Zed。

ローカル stdio

パッケージをインストールし、ローカルプロセスに API トークンを指定します。

python -m pip install mcp-serp
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
mcp-serp

Claude Desktop のローカル MCP では、開発者設定から開いたファイル（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）にこの項目をマージします。uvx を使うには、uv が PATH 上に必要です。

{
  "mcpServers": {
    "serp": {
      "command": "uvx",
      "args": ["mcp-serp"],
      "env": {"ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"}
    }
  }
}

このユーザーレベルのファイルは非公開にしてください。セルフホスト可能な HTTP では mcp-serp --transport http --port 8000 を使用します。適切なネットワークおよび TLS の制御がある場合に限り、外部に公開してください。ローカル実行でも、AceDataCloud API が呼び出されます。

サービスを使用する前の確認

1. https://serp.mcp.acedata.cloud/health が {"status":"ok"} を返すことは、エンドポイントに到達できることのみを確認します。
2. MCP クライアントがツールを読み込んでいることを確認します。serp_list_search_types と serp_get_usage_guide は、検索 API の料金が発生しないローカルのリファレンスツールです。これらのツールでは、下流 API へのアクセスや残高は確認できません。検索ツールは読み取り専用ですが、クレジットを消費します。同じ検索を繰り返すと、追加料金が発生する場合があります。
3. API を完全に確認する必要がある場合は、サービスの最新ドキュメントと表示されている料金を確認したうえで、有効な入力を指定して serp_google_search を呼び出します。

401 が発生した場合は、クライアントがどの認証方法を使用したか、トークンまたは OAuth セッションが有効かを確認してください。403 は、アカウントの権限またはコンテンツモデレーションの失敗を示している場合があります。返されたエラーを確認してください。残高不足や下流サービスの障害については、それぞれ個別に原因を調査する必要があります。ツールが一覧に表示されることやタスクが送信されたことだけでは、結果が正常に取得されたことの証明にはなりません。

利用可能なツール

検索ツール

ツール	説明
serp_google_search	あらゆるオプションを指定できる柔軟な Google 検索
serp_google_images	画像を検索
serp_google_news	ニュース記事を検索
serp_google_videos	動画を検索
serp_google_places	ローカルの場所やビジネスを検索
serp_google_maps	地図上の場所を検索

情報ツール

ツール	説明
serp_list_search_types	利用可能な検索タイプを一覧表示
serp_list_countries	地域設定用の国コードを一覧表示
serp_list_languages	地域設定用の言語コードを一覧表示
serp_list_time_ranges	時間範囲フィルターの選択肢を一覧表示
serp_get_usage_guide	詳細な使用ガイドを取得

使用例

基本的なウェブ検索

User: Search for information about artificial intelligence

Claude: I'll search for information about AI.
[Calls serp_google_search with query="artificial intelligence"]

時間フィルターを使ったニュース検索

User: What's the latest news about technology?

Claude: I'll search for recent tech news.
[Calls serp_google_news with query="technology", time_range="qdr:d"]

地域を指定した検索

User: Find popular restaurants in Tokyo

Claude: I'll search for restaurants in Tokyo.
[Calls serp_google_places with query="popular restaurants Tokyo", country="jp"]

画像検索

User: Find images of the Northern Lights

Claude: I'll search for aurora borealis images.
[Calls serp_google_images with query="Northern Lights aurora borealis"]

検索パラメーター

検索タイプ

タイプ	説明
search	通常のウェブ検索（デフォルト）
images	画像検索
news	ニュース記事
maps	地図の検索結果
places	ローカルビジネス
videos	動画の検索結果

時間範囲フィルター

コード	時間範囲
h	過去 1 時間
qdr:h	過去 1 時間
d	過去 1 日
qdr:d	過去 1 日
w	過去 1 週間
qdr:w	過去 1 週間
m	過去 1 か月
qdr:m	過去 1 か月
y	過去 1 年
qdr:y	過去 1 年

画像サイズフィルター（images 検索タイプ用）

large、medium、icon、2mp、4mp、6mp、8mp、10mp、12mp、15mp、20mp、40mp、70mp

よく使われる国コード

コード	国
us	アメリカ合衆国
uk	イギリス
cn	中国
jp	日本
de	ドイツ
fr	フランス

一般的な言語コード

コード	言語
en	英語
zh-cn	中国語（簡体字）
ja	日本語
es	スペイン語
fr	フランス語
de	ドイツ語

レスポンス構造

通常の検索結果

• knowledge_graph：エンティティ情報（企業、人など）
• answer_box：直接的な回答
• organic：タイトル、リンク、スニペットを含む通常の検索結果
• people_also_ask：関連する質問
• related_searches：関連するクエリ

画像検索結果

• images：URL とサムネイルを含む画像の検索結果

ニュース検索結果

• news：ソースと日付を含むニュース記事

設定

環境変数

変数	説明	デフォルト
ACEDATACLOUD_API_TOKEN	AceDataCloud の API トークン	必須
ACEDATACLOUD_API_BASE_URL	API のベース URL	https://api.acedata.cloud
ACEDATACLOUD_OAUTH_CLIENT_ID	OAuth クライアント ID（ホステッドモード）	—
ACEDATACLOUD_PLATFORM_BASE_URL	プラットフォームのベース URL	https://platform.acedata.cloud
SERP_REQUEST_TIMEOUT	リクエストのタイムアウト（秒）	30
LOG_LEVEL	ログレベル	INFO

コマンドラインオプション

mcp-serp --help

Options:
  --version          Show version
  --transport        Transport mode: stdio (default) or http
  --port             Port for HTTP transport (default: 8000)

開発

開発環境のセットアップ

# Clone repository
git clone https://github.com/AceDataCloud/SerpMCP.git
cd SerpMCP

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

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

テストの実行

# Run unit tests
pytest

# Run with coverage
pytest --cov=core --cov=tools

# Run integration tests (requires API token)
pytest tests/test_integration.py -m integration

コード品質

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy core tools

ビルドと公開

# Install build dependencies
pip install -e ".[release]"

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

プロジェクト構成

SerpMCP/
├── core/                   # Core modules
│   ├── __init__.py
│   ├── client.py          # HTTP client for SERP API
│   ├── config.py          # Configuration management
│   ├── exceptions.py      # Custom exceptions
│   └── server.py          # MCP server initialization
├── tools/                  # MCP tool definitions
│   ├── __init__.py
│   ├── search_tools.py    # Search tools
│   └── info_tools.py      # Information tools
├── prompts/                # MCP prompt templates
│   └── __init__.py
├── tests/                  # Test suite
│   ├── conftest.py
│   ├── test_client.py
│   └── test_config.py
├── deploy/                 # Deployment configs
│   └── production/
│       ├── deployment.yaml
│       ├── ingress.yaml
│       └── service.yaml
├── .env.example           # Environment template
├── .gitignore
├── CHANGELOG.md
├── Dockerfile             # Docker image for HTTP mode
├── docker-compose.yaml    # Docker Compose config
├── LICENSE
├── main.py                # Entry point
├── pyproject.toml         # Project configuration
└── README.md

API リファレンス

このサーバーは、AceDataCloud Google SERP APIをラップしています。

• Google SERP API のドキュメント

コントリビューション

コントリビューションを歓迎します。以下の手順でお願いします。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing）
5. プルリクエストを作成します

ドキュメント

ドキュメント

ライセンス

MIT ライセンスの詳細については、LICENSEを参照してください。

リンク

• AceDataCloud プラットフォーム
• Google SERP API
• Model Context Protocol
• MCP Python SDK

---

AceDataCloudが愛を込めて作成しました