SEOAnalytics Read MCP

WordPress、Google Search Console、Google Analytics 4 のSEO分析用データを取得するための、読み取り専用MCPサーバーです。

このサーバーは事故防止を優先して、取得だけに機能を限定しています。記事の作成、更新、削除、公開、メディアアップロード、GA4設定変更、Search Console設定変更はできません。

できること

• WordPressの記事一覧を取得する
• WordPressの記事本文、タイトル、URL、カテゴリ、タグ、更新日を取得する
• Search Consoleのクリック数、表示回数、CTR、平均掲載順位を取得する
• ページごとの検索クエリを取得する
• クエリごとの流入ページを取得する
• GA4のページビュー、セッション、ユーザー、流入元、ランディングページを取得する
• WordPress記事とGSC/GA4の数値をまとめて取得する

できないこと

安全のため、以下は実装していません。

• WordPress記事の作成
• WordPress記事の更新
• WordPress記事の削除
• 下書き作成
• 公開処理
• タグ、カテゴリ変更
• メディアアップロード
• GA4の設定変更
• Search Consoleのサイトマップ送信や削除

MCPツール一覧

wp.list_posts
wp.get_post
wp.search_posts

gsc.list_sites
gsc.get_search_performance
gsc.get_page_queries
gsc.get_query_pages

ga4.get_page_metrics
ga4.get_traffic_sources
ga4.get_landing_pages

seo.get_article_snapshot
seo.get_article_performance

フォルダ構成

SEOAnalytics/
  README.md
  Dockerfile
  docker-compose.yml
  pyproject.toml
  .env.example
  src/
    seo_data_reader_mcp/
      server.py
  tests/
  work/
  outputs/

1. 最初に.envを作る

.env.example をコピーして .env を作ります。

Windows PowerShellの場合:

Copy-Item .env.example .env

Ubuntu / WSLの場合:

cp .env.example .env

そのあと .env を編集します。

2. WordPressの設定

公開記事だけを読む場合は、まずこれだけで試せます。

WP_BASE_URL=https://example.com

例:

WP_BASE_URL=https://your-wordpress-site.example

WordPress REST APIのURLは、内部的には次のようになります。

https://example.com/wp-json/wp/v2/posts

非公開記事や認証が必要な情報も読みたい場合だけ、WordPressのアプリケーションパスワードを使います。

WP_USERNAME=reader@example.com
WP_APPLICATION_PASSWORD=

WordPress側の準備:

1. WordPress管理画面にログインします。
2. 読み取り専用に近い権限のユーザーを用意します。
3. ユーザーのプロフィール画面を開きます。
4. 「アプリケーションパスワード」を発行します。
5. 発行されたパスワードを WP_APPLICATION_PASSWORD に入れます。

注意: WordPress本体には完全な「REST API読み取り専用トークン」が標準で用意されているわけではありません。事故を避けるため、このMCP側ではGETリクエストしか実行しない作りにしています。

3. Google OAuthの長期設定

OpenCrawlなどのMCPクライアントで長期的に使う場合は、短命のアクセストークンではなく、Google OAuthの refresh_token を使うのがおすすめです。

.env には次の3つを入れます。

GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=
GOOGLE_REFRESH_TOKEN=

このMCPサーバーは、GOOGLE_REFRESH_TOKEN から新しいアクセストークンを自動取得して、Search Console APIとGA4 Data APIを読みます。

Google Cloud Consoleで有効化するAPI:

Google Search Console API
Google Analytics Data API

OAuth同意で許可するスコープ:

https://www.googleapis.com/auth/webmasters.readonly
https://www.googleapis.com/auth/analytics.readonly

アクセストークンはGoogle側で期限切れになりますが、refresh_token があればMCPサーバー側で自動更新します。

refresh tokenの取り方

1. Google Cloud Consoleでプロジェクトを作成します。
2. 「APIとサービス」から Google Search Console API と Google Analytics Data API を有効化します。
3. OAuth同意画面を設定します。
4. 「認証情報」からOAuthクライアントIDを作成します。
5. OAuth Playgroundなどで上記2つのスコープを許可し、refresh_token を取得します。

OAuth Playgroundを使う場合は、右上の歯車から Use your own OAuth credentials を有効にし、Google Cloud Consoleで作成した GOOGLE_CLIENT_ID と GOOGLE_CLIENT_SECRET を使ってください。

注意: GOOGLE_CLIENT_SECRET と GOOGLE_REFRESH_TOKEN は秘密情報です。Gitにコミットしたり、チャットにそのまま貼ったりしないでください。

.env の完成例:

WP_BASE_URL=https://your-wordpress-site.example

GSC_SITE_URL=https://your-wordpress-site.example/
GA4_PROPERTY_ID=123456789

GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=
GOOGLE_REFRESH_TOKEN=

GSC_ACCESS_TOKEN=
GA4_ACCESS_TOKEN=

4. Search Consoleの設定

Search Consoleを使う場合は、Search Consoleに登録されているプロパティ表記を .env に入れます。

GSC_SITE_URL=https://example.com/

GSC_SITE_URL はSearch Consoleに登録されているプロパティ表記と合わせてください。

URLプレフィックスプロパティの例:

GSC_SITE_URL=https://example.com/

ドメインプロパティの例:

GSC_SITE_URL=sc-domain:example.com

Search Consoleで使える主なツール:

gsc.list_sites
gsc.get_search_performance
gsc.get_page_queries
gsc.get_query_pages

一時的な接続テストだけなら、短命のOAuthアクセストークンを直接入れることもできます。

GSC_ACCESS_TOKEN=

ただし、これは期限切れになるため長期運用には向きません。

5. GA4の設定

GA4を使う場合は、GA4 Data API用のプロパティIDを .env に入れます。

GA4_PROPERTY_ID=123456789

GA4プロパティIDは、GA4管理画面のプロパティ詳細で確認できます。G-XXXXXXXXXX の測定IDではなく、数字だけのプロパティIDを使います。

GA4で使える主なツール:

ga4.get_page_metrics
ga4.get_traffic_sources
ga4.get_landing_pages

一時的な接続テストだけなら、短命のOAuthアクセストークンを直接入れることもできます。

GA4_ACCESS_TOKEN=

ただし、これは期限切れになるため長期運用には向きません。

6. Dockerで起動する

このプロジェクトのフォルダで実行します。

cd <PROJECT_DIR>

ビルド:

docker compose build seo-data-reader-mcp

MCPサーバーを起動:

docker compose run --rm -T seo-data-reader-mcp

MCPはstdioで通信するため、通常のWebサーバーのようにポート番号は出ません。OpenCrawlなどのMCPクライアントから起動コマンドとして呼び出します。

HTTPで常時稼働させる場合:

docker compose up -d seo-data-reader-mcp-http

HTTP版は次のURLで待ち受けます。

http://localhost:8765/mcp
http://<LAN_HOST>:8765/mcp

Web UIが古いHTTP+SSE形式を要求する場合は、次も使えます。

http://localhost:8765/sse
http://<LAN_HOST>:8765/sse

稼働確認:

docker compose ps

停止:

docker compose down

7. OpenCrawlへの設定例

Dockerで使う場合の例です。

{
  "mcpServers": {
    "seo-data-reader": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "<PROJECT_DIR>\\docker-compose.yml",
        "run",
        "--rm",
        "-T",
        "seo-data-reader-mcp"
      ],
      "env": {}
    }
  }
}

OpenCrawlからWSL経由でDockerを呼びたい場合の例です。

{
  "mcpServers": {
    "seo-data-reader": {
      "command": "wsl",
      "args": [
        "-e",
        "bash",
        "-lc",
        "cd '/path/to/SEOAnalytics' && docker compose run --rm -T seo-data-reader-mcp"
      ],
      "env": {}
    }
  }
}

Docker Composeは .env を読むため、通常はOpenCrawl側の env にGoogle認証情報を直接書かなくて大丈夫です。.env は docker-compose.yml と同じフォルダに置いてください。

Ubuntuサーバー上で、Dockerを使わずPythonで直接動かす場合の例です。

{
  "mcpServers": {
    "seo-data-reader": {
      "command": "python3",
      "args": ["-m", "seo_data_reader_mcp.server"],
      "cwd": "/path/to/SEOAnalytics",
      "env": {
        "PYTHONPATH": "/path/to/SEOAnalytics/src"
      }
    }
  }
}

UbuntuサーバーでもDockerを使う場合は、サーバー上の配置パスに合わせて docker-compose.yml の場所を変えてください。

8. ヘルメスエージェントへの設定例

ヘルメスエージェントからstdio起動する場合は、同梱の起動スクリプトをMCPサーバーとして登録してください。

設定例は hermes-agent.mcp.example.json に入っています。

{
  "mcpServers": {
    "seo-analytics": {
      "command": "powershell",
      "args": [
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "<PROJECT_DIR>\\scripts\\hermes-start.ps1"
      ],
      "env": {}
    }
  }
}

ヘルメスエージェント側にMCPサーバー設定画面、またはMCP設定JSONがある場合は、この seo-analytics の設定を追加します。

scripts/hermes-start.ps1 はプロジェクトフォルダへ移動してから次を実行します。

docker compose run --rm -T seo-data-reader-mcp

そのため、ヘルメスエージェント側が cwd を指定できない場合でも起動できます。.env はこれまで通り SEOAnalytics フォルダ直下に置いてください。

常時稼働しているHTTPサーバーへWeb UIから接続する場合は、hermes-agent.http.example.json の形式を使います。

{
  "mcpServers": {
    "seo-analytics": {
      "url": "http://localhost:8765/mcp",
      "transport": "streamable-http"
    }
  }
}

別PCやコンテナ上のWeb UIから接続する場合は、localhost を接続先ホスト名に置き換えてください。

http://<LAN_HOST>:8765/mcp

Web UIがSSE URLを求める場合は、次を指定してください。

http://<LAN_HOST>:8765/sse

HTTPサーバーを起動するPowerShellスクリプトも用意しています。

scripts\hermes-http-start.ps1

必要なら .env に MCP_HTTP_TOKEN を設定できます。その場合、Web UI側にも次のHTTPヘッダーを設定してください。

Authorization: Bearer <MCP_HTTP_TOKENの値>

9. 動作確認

WSL / Ubuntuでテストする場合:

cd /path/to/SEOAnalytics
PYTHONPATH=src python3 -m unittest discover -s tests -v

MCPのstdio応答を確認する場合:

PYTHONPATH=src python3 -m seo_data_reader_mcp.server < work/mcp_smoke_input.jsonl

Dockerでstdio応答を確認する場合:

Get-Content work\mcp_smoke_input.jsonl | docker compose run --rm -T seo-data-reader-mcp

HTTP版を確認する場合:

curl -s http://localhost:8765/health
curl -s -X POST http://localhost:8765/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

WSL経由でDockerのstdio応答を確認する場合:

wsl -e bash -lc "cd '/path/to/SEOAnalytics' && cat work/mcp_smoke_input.jsonl | docker compose run --rm -T seo-data-reader-mcp"

今回の確認では、WSL経由で以下が通っています。

docker compose ps
docker compose build seo-data-reader-mcp
cat work/mcp_smoke_input.jsonl | docker compose run --rm -T seo-data-reader-mcp

10. 代表的な使い方

WordPress記事一覧を取得:

wp.list_posts

特定の記事を取得:

wp.get_post
引数: { "id": 123 }

記事本文をプレーンテキスト付きで取得:

seo.get_article_snapshot
引数: { "id": 123 }

記事、Search Console、GA4をまとめて取得:

seo.get_article_performance
引数: {
  "id": 123,
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}

Search Consoleでページごとの検索クエリを取得:

gsc.get_page_queries
引数: {
  "page_url": "https://example.com/article/",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}

GA4でページ指標を取得:

ga4.get_page_metrics
引数: {
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}

11. よくあるエラー

WP_BASE_URL is required

.env に WP_BASE_URL が入っていません。

GSC_ACCESS_TOKEN is required

Search Console系ツールを使うための認証情報が入っていません。長期運用では GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_REFRESH_TOKEN を入れてください。

GA4_PROPERTY_ID is required

GA4の数字だけのプロパティIDが入っていません。

Google OAuth refresh did not return an access_token

GOOGLE_REFRESH_TOKEN からアクセストークンを取得できませんでした。OAuthスコープ、OAuthクライアントID、クライアントシークレット、refresh tokenを確認してください。

permission denied while trying to connect to the docker API

Docker Desktopが起動していないか、現在の環境からDocker APIへ接続できていません。Docker Desktopを起動し、WSL連携や権限を確認してください。

12. 安全設計

このMCPサーバーは、最初から事故を避けるために次の方針で作っています。

• MCPツールに書き込み系を用意しない
• WordPressはGETのみ
• Search Consoleは読み取り系エンドポイントのみ
• GA4はData APIのレポート取得のみ
• 認証情報がない場合は明示的にエラーを返す
• リライト、投稿、下書き作成は別MCPに分離する前提

OpenCrawlには、このMCPを「データを読む係」として接続するのがおすすめです。リライト案の作成やWordPressへの反映は、別MCPに分けると安全です。