seo-analytics-mcp

Google Search Console, GA4 및 IndexNow — MCP 서버로 제공.

Claude에게 내 사이트에 대해 물어보세요. 무엇이 랭킹에 오르는지, 무엇이 바뀌었는지, 무엇이 색인되었는지, 무엇이 전환되는지.

"Which pages lost the most clicks in the last 28 days versus the 28 before?"
"How is /pricing doing?"
"Is https://example.com/new-post indexed yet?"
"Which pages rank on page one but get almost no clicks?"
"Top 20 queries for the blog last month, and which of them convert in GA4."

내 Google 계정을 내 Google Cloud 프로젝트의 OAuth 클라이언트에 대해 직접 인증합니다. 내 액세스가 다른 사람을 통해 흐르는 일은 전혀 없으며, 이 저장소에는 자격 증명이 포함되어 있지 않고, 사용하는 모든 Google 할당량은 내 것이 됩니다.

목차

설치 · 설정 · 7일 문제 · 도구 · 응답 형식 · 구성 · 쓰기 작업 · 프로필 · 설계 · 문제 해결 · 개발

Related MCP server: GSC Analyst Connector

설치

Python 3.10+ 및 uv 필요.

uvx seo-analytics-mcp doctor      # no install needed — prints your setup steps, in order

doctor는 온보딩 경험 전체입니다. 각 단계에서 정확히 무엇이 빠졌고 무엇을 실행해야 하는지 알려줍니다. 여기서 다른 것을 읽지 않는다면, 그것을 실행하세요.

설정

Google Cloud 콘솔에서 여섯 번의 클릭, 그 다음 명령어 하나. 10분, 한 번이면 됩니다.

Google Cloud 프로젝트 만들기 — 또는 기존 프로젝트 재사용. console.cloud.google.com/projectcreate

API 활성화. Search Console은 필수이고, GA4 쌍은 선택 사항입니다.

searchconsole · analyticsdata · analyticsadmin

동의 화면을 구성한 다음 앱 게시를 누르세요. console.cloud.google.com/auth/overview

외부를 선택하고 게시하세요. 본인 앱의 유일한 사용자는 본인이므로 Google의 개인 사용 예외가 적용되어 검증이 필요 없습니다. Workspace 사용자는 대신 내부를 선택할 수 있습니다.

게시 단계를 건너뛰지 마세요 — 아래 참조.

데스크톱 앱 유형의 OAuth 클라이언트를 만들고 JSON을 다운로드하세요. console.cloud.google.com/auth/clients

웹 애플리케이션 클라이언트는 이 서버에 필요한 루프백 리디렉션을 수행할 수 없습니다. doctor는 이 특정 실수를 확인합니다. 왜냐하면 그것이 가장 쉽게 저지르는 실수이기 때문입니다.

터미널에서 한 번 인증하세요:

uvx seo-analytics-mcp auth --client-secret ~/Downloads/client_secret_*.json

브라우저가 열립니다. Google이 *"Google hasn't verified this app"*이라고 표시합니다 — 본인 클라이언트에서는 예상된 것입니다: 고급 → 계속. 토큰은 프로필 디렉터리에 모드 0600으로 저장됩니다.

확인한 다음 연결하세요:

uvx seo-analytics-mcp doctor      # eleven checks; exit 0 means it will work

연결하기

claude mcp add seo \
  -e GSC_DEFAULT_SITE=sc-domain:example.com \
  -e GA4_DEFAULT_PROPERTY=properties/123456789 \
  -- uvx seo-analytics-mcp

{
  "mcpServers": {
    "seo": {
      "command": "uvx",
      "args": ["seo-analytics-mcp"],
      "env": {
        "GSC_DEFAULT_SITE": "sc-domain:example.com",
        "GA4_DEFAULT_PROPERTY": "properties/123456789"
      }
    }
  }
}

그런 다음 Claude Desktop을 완전히 종료하고(⌘Q — 창을 닫는 것만으로는 충분하지 않음) 다시 여세요.

[!NOTE] 해당 구성에는 자격 증명 경로가 없습니다. 토큰은 seo-mcp auth가 기록한 프로필 디렉터리에 있으므로 전체 블록을 GitHub 이슈에 붙여넣어도 안전합니다.

7일 문제

[!WARNING] 서버가 작동하다가 약 일주일 후에 멈춘다면, 이것이 이유입니다.

Google은 게시 상태가 여전히 테스트인 외부 OAuth 앱에 대해 7일 후 만료되는 리프레시 토큰을 발급합니다. 명백한 설정 경로 — 프로젝트 만들기, 클라이언트 만들기, 자신을 테스트 사용자로 추가하기 — 는 그 상태에 머물게 합니다.

해결책은 한 번의 클릭입니다: 동의 화면에서 대상을 외부로 설정하고 앱 게시를 누르세요. 그런 다음 uvx seo-analytics-mcp auth --reauth.

doctor는 여전히 테스트 토큰일 가능성이 있는 어린 토큰을 표시하고, 서버의 모든 invalid_grant 오류는 이 내용을 전체적으로 설명합니다. 서버의 버그는 아닙니다 — 하지만 이에 대해 제기되는 가장 흔한 이슈가 될 것입니다.

도구

13개의 도구: 10개는 상위 운영에 매핑되고, 2개는 소스를 결합하며, 1개는 모델이 혼란스러운 사용자에게 무엇을 해야 하는지 알려주기 위해 존재합니다.

응답 형식

모든 읽기 도구는 동일한 네 개의 키를 반환합니다. 제한적이고, 자체 설명적이며, 자체 주의 사항을 담고 있습니다.

{
  "summary": {
    "source": "gsc",
    "rows_returned": 10,        // what you see
    "rows_matched": 1847,       // what exists upstream
    "date_range": "2026-07-29..2026-08-25",   // resolved, always echoed
    "data_state": "final",
    "totals": { "clicks": 4730, "impressions": 512903, "ctr": 0.0092, "position": 12.4 }
  },
  "rows": [ /* capped at min(row_limit, 1000) */ ],
  "notes": [
    "Google anonymises rare queries: these rows do NOT sum to property totals.",
    "dataState=final excludes the most recent 2-3 days.",
    "1837 further rows were not included inline."
  ],
  "export": "~/.../exports/a1b2c3.csv"        // only when rows spilled
}

모든 곳에서 세 가지 규칙이 적용됩니다:

합계는 표시된 행뿐만 아니라 가져온 모든 행을 포함합니다 — 10개의 행과 10개의 합계를 보는 모델은 잘림과 현실을 구분할 수 없습니다. 비율은 절대 평균화되지 않습니다: ctr는 클릭수 ÷ 노출수에서 다시 계산되고, position은 노출 가중치가 적용되며, engagementRate는 참여 ÷ 세션입니다.

주의 사항은 데이터와 함께 이동합니다. 주의 사항을 아는 계층이 이를 추가합니다: 클라이언트는 query 차원이 요청되었음을 알고, shape()는 얼마나 많은 행을 버렸는지 알고, GA4는 응답이 샘플링되었음을 알고 있습니다. 독스트링만으로는 모델이 숫자를 보고 있는 바로 그 순간에 이를 잃어버립니다.

오류는 해결책을 명명합니다. 403은 어떤 권한을 확인해야 하고 어디에서 확인해야 하는지 알려줍니다 — 절대 원시 Google 오류 본문이 아닙니다.

The authorised Google account has no access to sc-domain:example.com. Confirm the
account you authorised is the one with access — Search Console grants are per-property
under Settings > Users and permissions, GA4 grants are per-property under Admin >
Property access management. If access was added recently, run `seo-mcp auth --reauth`.

구성

모든 변수는 선택 사항입니다. 우선 순위: 도구 인수 → 환경 → 프로필 config.json.

날짜

모든 날짜 인수는 YYYY-MM-DD, today, yesterday 또는 NdaysAgo를 허용합니다. 응답은 실제로 사용한 절대 범위를 반영합니다. 모델이 오늘 날짜를 잘못 추측하면 *"트래픽이 0으로 떨어졌다"*로 읽히는 빈 결과가 생성되기 때문입니다.

Search Console은 2~3일 지연되고 약 16개월을 보유합니다. 해당 범위를 벗어나는 범위는 조용히 아무것도 반환하지 않는 대신 표시되거나 거부됩니다. GA4는 속성 자체 시간대에서 보고하므로 날짜가 Search Console과 정확히 일치하지 않습니다 — 응답은 중요한 곳에서 이를 명시합니다.

쓰기 작업

두 도구는 내 컴퓨터 외부의 세계에 영향을 미칩니다. 둘 다 의도적으로 불편하게 설계되었습니다.

[!IMPORTANT] confirm 플래그만으로는 안전 메커니즘이 아닙니다 — 모델이 채우는 인수일 뿐이며, 잘못된 URL을 생성하는 동일한 오독이 그 옆에 confirm=true를 생성합니다.

토큰은 드라이 런 없이는 위조할 수 없고, URL 하나를 변경하면 더 이상 일치하지 않습니다. 두 도구 모두 destructiveHint 주석도 포함하므로, 파괴적 도구를 자체 승인 프롬프트 뒤에 게이트하는 클라이언트는 그렇게 할 것입니다.

읽기 전용 범위가 기본값입니다. 낯선 사람이 설치한 SEO 도구가 즉시 Search Console 속성 수정 권한을 요청한다면 합리적으로 거절할 것입니다.

프로필

한 머신에 여러 Google 계정 — 클라이언트 속성을 나란히 보유하는 에이전시용.

uvx seo-analytics-mcp auth --profile client-a --client-secret ./client-a.json
uvx seo-analytics-mcp auth --profile client-b --client-secret ./client-b.json
uvx seo-analytics-mcp profiles list

MCP 서버 항목별로 SEO_MCP_PROFILE을 설정하세요. 캐시 키에는 프로필이 포함되므로 두 계정이 서로의 데이터를 제공할 수 없습니다.

프로필은 하나의 디렉터리입니다 — 사용자에게 삭제를 요청하게 될 첫 번째 것입니다:

uvx seo-analytics-mcp profiles rm client-a --yes

이들은 ~/Library/Application Support/seo-mcp/ (macOS), $XDG_CONFIG_HOME/seo-mcp/ (Linux) 또는 %APPDATA%\seo-mcp\ (Windows)에 있습니다.

설계

네 개의 계층, 엄격하게 하향식. 이것을 잘못하면 인증 흐름이 도구 호출 안에 들어가게 되며, 전체 설계가 방지하려는 것이 바로 그 실패입니다.

flowchart TD
    subgraph L4["Entry points"]
        S[server.py<br/><i>MCPServer, stdio</i>]
        C[cli.py<br/><i>auth · doctor · profiles · serve</i>]
    end
    subgraph L3["Tools — argument surface, docstrings, cache policy"]
        T[13 handlers<br/><i>no HTTP, no credentials, no row shaping</i>]
    end
    subgraph L2["Clients — the only modules that speak HTTP"]
        G[gsc.py]
        A[ga4.py]
        I[indexnow.py]
    end
    subgraph L1["Leaves — importable by anyone, import nobody"]
        LV[shaping · errors · config · cache · auth/store · auth/scopes]
    end
    F[auth/flow.py<br/><i>loopback + PKCE · opens a browser</i>]

    S --> T
    C --> T
    C -.->|only reachable from here| F
    T --> G & A & I
    G & A & I --> LV

브라우저 흐름은 도구 호출 안에서 절대 실행되어서는 안 됩니다. 사용자가 동의 화면을 끝낼 때까지 stdio에서 차단되는 MCP 도구는 중단된 서버처럼 보이며, 모델이 도울 방법이 없습니다. 한 번 실행하는 하나의 CLI 명령이 전체 차이입니다 — 그리고 테스트가 모든 모듈의 AST를 순회하여 이를 강제합니다.

테스트가 기계적으로 강제하는 다른 규칙: shaping.py는 Google 라이브러리를 가져오지 않고(그래서 행 로직이 자격 증명 없이 완전히 단위 테스트 가능), 도구는 HTTP 라이브러리를 가져오지 않으며, 서버 경로의 어떤 것도 print()를 호출하지 않습니다 — stdio 전송에서 stdout은 JSON-RPC를 전달하며 단 하나의 잘못된 print가 스트림을 손상시킵니다.

문제 해결

모든 문제 보고에는 seo-mcp doctor --json이 포함되어야 합니다. 여기에는 자격 증명이 없습니다. 경로, 버전, 통과한 검사와 응답한 API만 포함됩니다.

개발

uv sync --extra dev
uv run pytest -q                    # 147 tests · no credentials · no network
uv run python scripts/smoke.py      # drives the server over real stdio JSON-RPC
uv run ruff check src tests

python3 -m venv .venv && ./.venv/bin/pip install -e ".[dev]"
./.venv/bin/python -m pytest -q
./.venv/bin/python scripts/smoke.py ./.venv/bin/seo-mcp

scripts/smoke.py는 서버를 하위 프로세스로 시작하고, MCP 핸드셰이크를 완료하며, 도구를 나열하고 여러 도구를 호출합니다. 임시 프로필 디렉터리를 사용하므로 실제 토큰은 건드리지 않습니다. Google 자격 증명이 있기 전에 프로토콜 측이 작동하는지 확인하는 가장 빠른 방법입니다.

직접 시험해 보려면 MCP Inspector는 Node만 있으면 됩니다:

npx @modelcontextprotocol/inspector ./.venv/bin/seo-mcp            # web UI
npx @modelcontextprotocol/inspector --cli ./.venv/bin/seo-mcp \
    --method tools/call --tool-name auth_status                    # scriptable

자동화된 테스트로 다루지 않는 부분: OAuth 흐름 자체와 실제 IndexNow 제출입니다. 둘 다 사람과 실제 도메인이 필요하며, 이를 모킹하면 모크만 테스트하게 됩니다. 이들은 짧은 수동 릴리스 체크리스트에 속합니다.

하지 않을 두 가지

[!NOTE] IndexNow는 Google에 도달하지 않습니다. 참여자는 Bing, Yandex, Naver, Seznam.cz, Yep 및 Amazon입니다. 하나의 엔드포인트가 이들 모두에게 전파됩니다. Google은 참여하지 않으며, Google 자체 Indexing API는 JobPosting 또는 BroadcastEvent 구조화 데이터가 포함된 페이지만 허용합니다. 더 빠른 Google 색인을 기대하고 이 도구를 설치한다면 실망할 것입니다.

[!NOTE] 쿼리 행은 합계와 일치하지 않습니다. Google은 드문 쿼리를 익명화하므로 query dimension으로 분류하면 수가 부족하게 집계됩니다. 해당 dimension을 포함하는 모든 응답은 이 주의 사항을 반복합니다. 그렇지 않으면 해당 행을 받은 모델이 자신 있게 잘못된 백분율을 계산하기 때문입니다.

기여

이슈와 풀 리퀘스트를 환영합니다. 자격 증명이 필요 없는 테스트 스위트는 Python 3.10 및 3.13에서 Linux, macOS, Windows 전반에 걸쳐 모든 푸시에서 실행됩니다. 로컬에서 통과하면 CI에서도 통과합니다.

도구 이름을 바꾸거나 인수를 변경하면 사용자가 저장한 모든 프롬프트가 깨집니다. 이러한 변경은 CHANGELOG.md에 기록되며 1.0 이전에는 minor 버전, 이후에는 major 버전으로 올라갑니다.

라이선스

MIT.