Google Search Console MCP

Google Search Console API용 MCP 서버 — 검색 실적 데이터, URL 색인 상태, 사이트맵 관리 및 속성 목록.

하나의 코드베이스에서 세 가지 방식으로 실행됩니다: stdio(로컬, npx 사용), Streamable HTTP(자체 호스팅), Cloudflare Workers(URL에서 호스팅). MCP 2026-07-28을 구현하며 2025-11-25, 2025-06-18, 2025-03-26으로 자동 폴백하므로 프로토콜 변경 양쪽의 클라이언트에서 모두 작동합니다.

런타임 의존성 제로.

빠른 시작

npx google-search-console-mcp auth

Google OAuth 클라이언트 생성 과정을 안내하고, 동의 흐름을 실행하며, 라이브 API에 대해 자격 증명을 검증하고, MCP 클라이언트에 붙여넣을 수 있는 구성 블록을 출력합니다. 3분이면 되고, 대부분은 Google Cloud UI를 기다리는 시간입니다.

그런 다음 출력된 JSON을 클라이언트 구성에 넣고 다시 시작하세요.

Related MCP server: searchconsole-mcp

도구

Search Console API v1의 모든 메서드와 두 가지 복합 도구입니다.

사이트 인증과 sites.add/sites.delete는 의도적으로 노출하지 않습니다. 속성 추가 및 인증은 브라우저 흐름으로, 에이전트 도구에 들어맞지 않습니다.

서버는 또한 에이전트가 필요할 때 읽을 수 있는 프롬프트(performance_review, indexing_audit, query_opportunities, sitemap_health)와 리소스(gsc://guide/search-analytics, gsc://guide/url-inspection, gsc://guide/sitemaps)를 제공합니다.

인증

1단계 — Google OAuth 클라이언트 만들기

이 작업은 한 번만 하면 됩니다. 서버가 대신 해줄 수 없습니다. Google은 콘솔에서 사람이 필요하기 때문입니다.

1. Google Cloud Console을 열고 프로젝트를 선택하거나 만듭니다.

2. 해당 프로젝트에서 Search Console API를 사용 설정합니다.

3. OAuth 동의 화면을 구성합니다. 개인용으로는 외부로 해도 됩니다. 테스트 사용자에 자신의 Google 계정을 추가하세요.

4. 사용자 인증 정보 → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID로 이동합니다. 애플리케이션 유형은 데스크톱 앱을 선택합니다.

5. 클라이언트 ID와 클라이언트 비밀번호를 복사합니다.

테스트 vs 게시. 동의 화면이 테스트 상태인 동안 Google은 7일 후에 새로고침 토큰을 만료시키므로 매주 auth를 다시 실행해야 합니다. 앱을 게시하면(동의 화면 → 앱 게시) 토큰이 지속됩니다. 단일 사용자 내부 도구의 경우 webmasters 범위만 유지하면 게시는 안전하며 Google의 검증 검토가 필요하지 않습니다.

2단계 — 설정 흐름 실행

npx google-search-console-mcp auth

127.0.0.1에서 제공되는 작은 설정 페이지가 열립니다. 클라이언트 ID와 비밀번호를 붙여넣고 전체 또는 읽기 전용 액세스를 선택하면 동의 흐름을 실행하고, 코드(PKCE)를 새로고침 토큰으로 교환하며, list_sites를 호출하여 자격 증명이 작동하는지 확인합니다. 자격 증명이 도달할 수 있는 정확한 속성을 보여줍니다.

마지막 페이지에는 자격 증명 블롭과 Claude Desktop, Claude Code, 원격 배포용으로 붙여넣을 수 있는 구성이 각각 복사 버튼과 함께 표시됩니다. 동일한 값은 대체 수단으로 터미널에도 출력됩니다.

헤드리스 머신이나 SSH를 통한 경우 프롬프트 기반 버전인 auth --terminal을 대신 사용하세요.

자격 증명 블롭을 받게 됩니다. 클라이언트 ID, 클라이언트 비밀번호, 새로고침 토큰이 포함된 base64url 인코딩 JSON입니다:

eyJ2IjoxLCJjcmVkZW50aWFscyI6eyJ0eXBlIjoib2F1dGhfcmVmcmVzaF90b2tlbiIsImNsaWVu…

블롭을 비밀번호처럼 취급하세요. 이 블롭을 가진 사람은 myaccount.google.com/permissions에서 해지할 때까지 Search Console에 접근할 수 있습니다.

단일 불투명 문자열로 존재하므로 하나의 값에 서버가 필요한 모든 것이 담깁니다. 디스크의 자격 증명 파일 없이 환경 변수나 Authorization 헤더에 바로 넣을 수 있습니다.

OAuth 흐름의 대안

서비스 계정. CI 및 팀 소유 속성에 유용합니다. Google Cloud에서 계정을 만든 다음, Search Console의 속성(설정 → 사용자 및 권한)에서 client_email을 사용자로 추가하세요. 다운로드한 키 파일을 직접 인코딩하세요:

base64 -i service-account.json | tr -d '\n'

서버는 raw 서비스 계정 키를 블롭으로 허용합니다. 래퍼가 필요 없습니다.

기존 액세스 토큰. {"type":"access_token","access_token":"ya29..."}로 설정합니다. 새로고침이 불가능하므로 단기 스크립트에만 적합합니다.

범위

auth 중에 읽기 전용을 선택하면 더 좁은 범위를 요청합니다. 서버의 --read-only는 별도의 이중 안전 장치로, 변경 도구가 API에 도달하기 전에 거부합니다.

실행

로컬 (stdio)

auth가 출력한 구성:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "google-search-console-mcp"],
      "env": { "GSC_CREDENTIALS": "<your blob>" }
    }
  }
}

구성 파일 위치:

매번 npx를 거치지 않으려면 제대로 설치하세요:

npm install -g google-search-console-mcp

자체 호스팅 HTTP

GSC_CREDENTIALS=<blob> npx google-search-console-mcp http --port 8787

POST http://127.0.0.1:8787/mcp를 제공합니다. 기본적으로 루프백에 바인딩됩니다. 노출하려면 의도적으로 --host 0.0.0.0을 전달하고, 노출한다면 TLS를 앞에 두세요.

브라우저 기반 클라이언트는 이름을 지정하지 않으면 거부됩니다. 자체 자격 증명을 보유한 서버는 방문하는 모든 페이지에서 구동될 수 있기 때문입니다. 일반 MCP 클라이언트는 Origin을 보내지 않으므로 영향을 받지 않습니다. 브라우저 클라이언트는 origin을 나열해야 합니다:

npx google-search-console-mcp http --allowed-origins http://localhost:6274   # MCP Inspector

거부된 origin은 브라우저가 읽을 수 없는 403을 받습니다(설계상 거부 시 CORS 헤더가 없음), 따라서 일반적인 CORS 오류로 표시됩니다. 브라우저 클라이언트가 연결되지 않으면 서버의 Origins: 시작 줄을 확인하세요. --allowed-origins '*'는 검사를 비활성화합니다.

Cloudflare Workers

git clone https://github.com/russjeffery/google-search-console-mcp.git
cd google-search-console-mcp
npm install
npx wrangler deploy

엔드포인트는 https://google-search-console-mcp.<subdomain>.workers.dev/mcp입니다.

기본적으로 Worker는 비밀을 저장하지 않습니다. 각 클라이언트는 자체 자격 증명 블롭을 bearer 토큰으로 보내므로 공유 배포는 누구의 Google 자격 증명도 보유하지 않으며, 같은 URL의 다른 사용자는 자신의 속성만 볼 수 있습니다.

대신 프라이빗 단일 테넌트 배포를 원한다면:

npx wrangler secret put GSC_CREDENTIALS     # your blob
npx wrangler secret put MCP_SHARED_SECRET   # token clients must present

클라이언트는 블롭 대신 공유 비밀을 보냅니다.

wrangler.jsonc의 선택적 vars:

원격 서버에 클라이언트 연결

{
  "mcpServers": {
    "google-search-console": {
      "type": "http",
      "url": "https://your-worker.workers.dev/mcp",
      "headers": { "Authorization": "Bearer <your blob>" }
    }
  }
}

Claude 웹 또는 데스크톱 UI에서 설정 → 커넥터 → 사용자 지정 커넥터 추가 아래에 추가하세요.

자신의 배포에 맞게 채워서 출력하세요:

npx google-search-console-mcp config --url https://your-worker.workers.dev/mcp

CLI

google-search-console-mcp [command] [options]

  stdio     Run as a stdio MCP server (default)
  http      Run a local Streamable HTTP MCP server
  auth      Guided setup in your browser: OAuth flow, blob, client config
  config    Print client config for existing credentials
  doctor    Verify credentials by calling the API

doctor는 문제가 있을 때 가장 먼저 사용하는 도구입니다. "자격 증명이 잘못됨"과 "클라이언트가 서버를 시작할 수 없음"을 구분해 줍니다.

옵션: --credentials <blob>, --site <siteUrl>, --read-only, --port, --host, --endpoint, --secret, --allowed-origins, --url, --terminal, --no-browser.

--allowed-origins는 쉼표로 구분된 목록을 받습니다. 미설정이면 비브라우저 클라이언트만 허용합니다. 항목은 대소문자를 구분하지 않고 일치되며 끝의 슬래시는 무시됩니다.

--site는 기본 속성을 설정하여 도구가 siteUrl을 생략할 수 있게 합니다. 배포가 하나의 사이트만 다루는 경우에 편리합니다.

프로토콜 지원

2026-07-28 개정판은 Streamable HTTP를 크게 변경했습니다: initialize 핸드셰이크 없음, 세션 없음, Mcp-Session-Id 없음, GET 스트림 없음, params._meta의 요청별 메타데이터가 HTTP 헤더로 미러링됩니다. 공식 TypeScript SDK는 아직 이를 구현하지 않으므로 여기의 프로토콜 계층은 손으로 작성되었으며 이중 시대를 지원합니다.

시대는 요청별로 감지됩니다. 최신 _meta를 담은 요청은 최신으로 처리되고, initialize는 레거시를 선택합니다. 엔드포인트의 GET 및 DELETE는 개정판이 규정한 대로 405를 반환합니다.

헤더 검증은 기본적으로 사양에 따라 엄격합니다. 클라이언트가 헤더를 미러링하지 않고 최신 _meta를 보내는 경우 다운그레이드 대신 MCP_STRICT_HEADERS=0(또는 --loose-headers)을 설정하세요.

인증에 관하여: 스펙의 OAuth 2.1 흐름은 서버가 자체 인증 서버를 둔 리소스 서버라고 가정합니다. 그러나 이 서버는 베어러 토큰을 사용하여 Google 자격 증명을 직접 전달합니다 — 스펙은 사용자 정의 전략을 허용하며, 이는 호스팅 배포가 비밀을 보관하지 않고 사용자 데이터베이스가 필요 없음을 의미합니다. 그 대가로 자동 OAuth 검색을 기대하는 클라이언트는 위에 표시된 대로 헤더를 수동으로 구성해야 합니다.

데이터 다루기

Search Console 데이터의 네 가지 속성 때문에 대부분의 잘못된 결론이 나옵니다. 도구 설명과 번들된 스킬이 이를 자세히 다루며, 간단히 요약하면:

1. 데이터는 약 3일 지연됩니다. lastDays를 사용하면 도구가 안전한 기간을 선택합니다. 오늘로 끝나는 범위는 가짜 하락을 보여줍니다.

2. 쿼리 데이터는 개인정보 보호 필터링됩니다. query로 그룹화하면 드문 쿼리가 조용히 누락되므로 쿼리 수준 클릭 수는 속성 합계와 일치하지 않습니다. 그 차이는 손실된 트래픽이 아닙니다.

3. 위치는 반전됩니다. 위치 3이 위치 8보다 낫습니다. 음수 변화는 개선입니다. compare_search_analytics는 명시적인 improved 플래그를 반환합니다.

4. 평균은 상쇄됩니다. 평평한 헤드라인 수치는 큰 상쇄 움직임을 일상적으로 숨깁니다. 아무것도 변하지 않았다고 결론 내리기 전에 페이지 또는 쿼리별로 그룹화하세요.

할당량

• 검색 분석: 속성당 분당 약 1,200개 쿼리.

• URL 검사: 속성당 하루 약 2,000개 — 제약 조건입니다. 의도적으로 샘플링하세요.

API로 사용할 수 없는 것

집계 색인 적용 범위 보고서, 실시간 URL 테스트, 색인 요청, Core Web Vitals, 수동 조치, 보안 문제, 링크 보고서 및 제거는 API에 해당하는 기능이 없으므로 여기에 없습니다. URL별 inspect_url이 적용 범위 질문에 대한 가장 가까운 대안입니다.

에이전트 스킬

skills/google-search-console/은 에이전트가 이러한 도구를 잘 사용하도록 가르치는 즉시 설치 가능한 스킬입니다 — 위의 함정들, 트래픽 변화를 위한 진단 사다리, 기회 발견 휴리스틱, 그리고 적용 범위 상태 조회 테이블이 포함됩니다.

cp -r skills/google-search-console ~/.claude/skills/

동일한 참고 자료는 런타임에 서버의 gsc://guide/* 리소스를 통해 제공되므로 스킬이 설치되지 않은 에이전트도 읽을 수 있습니다.

개발

npm install
npm run build       # compile to dist/
npm run typecheck
npm test
npm run cf:dev      # Worker locally via wrangler

HTTP 전송에 대한 빠른 수동 확인:

GSC_CREDENTIALS=<blob> npm run build && node dist/bin/cli.js http &

curl -s http://127.0.0.1:8787/mcp \
  -H 'content-type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' | jq '.result.tools[].name'

문제 해결

보안

• 자격 증명 블롭은 Google 액세스 권한입니다. 커밋하지 말고 공유 문서에 붙여넣지 마세요. myaccount.google.com/permissions에서 취소하세요.

• HTTP 모드는 기본적으로 127.0.0.1에 바인딩되고 DNS 리바인딩을 차단하기 위해 ALLOWED_ORIGINS에 대해 Origin을 검증합니다. 설정하지 않으면 브라우저 출처가 허용되지 않습니다 — 명시적으로 나열하거나 *를 사용하여 검사를 거부하세요. /health와 /는 예외이며 자격 증명이 필요한 기능을 노출하지 않습니다.

• 공유 비밀 비교는 길이 검사와 상수 시간 비교를 사용합니다.

• 기본 Worker 배포는 자격 증명을 전혀 저장하지 않습니다.

• --read-only / GSC_READ_ONLY=1은 부여된 OAuth 범위와 독립적으로 사이트맵 변경을 차단합니다.

라이선스

MIT