Keyword Research MCP

Keyword Research MCP は、Google Ads のキーワードプランニングの証拠を取得して正規化するための軽量なローカル MCP サーバーです。現在活発に開発中であり、現在のリポジトリには、実行可能なプロジェクト基盤に加えて、型付けされテスト済みのリサーチインターフェースと本番用 Google Ads アダプタが含まれています。実装計画に記載されている MCP ツールの登録はまだ構築中です。

Google Ads の有料競合は広告主の活動を表します。このプロジェクトはそれをオーガニック検索順位の難易度として提示するものではなく、複合キーワードスコアを計算するものでもありません。

要件

• Python 3.10 through 3.14

• uv

テストには Google Ads の認証情報は必要ありません。本番アダプタが Google Ads に接続する際には必要です。

Related MCP server: Google Ads MCP Server

Google Ads 設定

本番アダプタは google-ads==31.2.0 を使用し、Google Ads API v25 を明示的に選択します。ターゲット顧客は1つだけ、認証方法は1つだけ設定してください。顧客 ID にはハイフンを含めることができます。メモリ内で正規化されます。

ユーザー OAuth の場合は、次を設定します:

export GOOGLE_ADS_DEVELOPER_TOKEN="developer-token-placeholder"
export GOOGLE_ADS_CUSTOMER_ID="123-456-7890"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="987-654-3210" # optional manager account
export GOOGLE_ADS_CLIENT_ID="client-id-placeholder"
export GOOGLE_ADS_CLIENT_SECRET="client-secret-placeholder"
export GOOGLE_ADS_REFRESH_TOKEN="refresh-token-placeholder"

サービスアカウントの場合は、3つのユーザー OAuth 設定を省略して、次を設定します:

export GOOGLE_ADS_DEVELOPER_TOKEN="developer-token-placeholder"
export GOOGLE_ADS_CUSTOMER_ID="123-456-7890"
export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/service-account.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="ads-user@example.test" # optional

あるいは、GOOGLE_ADS_CONFIGURATION_FILE_PATH をローカルの google-ads.yaml に指定します:

developer_token: developer-token-placeholder
customer_id: "123-456-7890"
login_customer_id: "987-654-3210"
client_id: client-id-placeholder
client_secret: client-secret-placeholder
refresh_token: refresh-token-placeholder

オプションのプロセス設定は、KEYWORD_RESEARCH_CACHE_CAPACITY（デフォルト 128）と KEYWORD_RESEARCH_LOG_LEVEL（デフォルト INFO）です。認証情報ファイル、google-ads.yaml、および .env ファイルは Git によって無視されます。

セットアップと実行

uv sync
uv run keyword-research-mcp

コマンドは stdio 上で実行されるため、MCP クライアントを静かに待機し、プロトコルメッセージを標準出力にのみ書き込みます。

開発

CI で使用されるのと同じ品質ゲートを実行します:

uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest
uv build

意図されたツール契約、アーキテクチャ、提供フェーズ、および製品境界については、実装計画 を参照してください。

ライセンス

MIT