search-console-mcp

Google Search Console용 MCP 서버로, 공식 Search Console API를 AI 에이전트용 도구로 노출합니다.

이 서버의 초점은 검색 성과와 인덱스 상태입니다 — 쿼리, 페이지, 국가, 기기, 날짜별로 클릭 수, 노출 수, CTR 및 순위를 조회하고, URL이 색인되었는지와 색인되지 않은 이유인 이유를 확인하며, 계정의 사이트맵과 속성을 관리합니다.

의도적으로 지원하지 않는 기능: URL의 (재)색인 요청은 하지 않습니다 — 별도의 Indexing API는 채용 공고 및 라이브 스트리밍 페이지만 지원하고, 속성 소유자 확인은 지원하지 않는 경우(소유 고자가 각 속성에 서비스 계정을 추가해야 함), Google Analytics 데이터도 지원하지 않습니다(관련 없는 Analytics Data API는 지원하지 않음).

삭제는 옵트인입니다. delete_sitemap 및 delete_site는 GOOGLE_SEARCH_CONSOLE_ALLOW_DESTRUCTIVE가 설정된 경우에만 등록됩니다 — 구성을 참조하세요.

설치

claude mcp add search-console \
  -e GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
  -e GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
  -- npx -y @orellbuehler/search-console-mcp

-e 플래그는 반드시 -- 구분자 앞에 와야 합니다. -- 뒤의 내용은 구성으로 읽히지 않고 서버 프로세스로 전달됩니다.

서비스 계정 키 발급

1. Google Cloud 콘솔에서 프로젝트를 선택하거나 생성하고 Google Search Console API를 사용 설정합니다.

2. IAM 및 관리자 → 서비스 계정 → 서비스 계정 만들기로 이동합니다. 선택 사항인 "액세스 권한 부여" 단계는 건너뛸 수 있습니다 — Search Console 권한은 Cloud IAM 역할이 아니라 별도로 부여됩니다.

3. 새 서비스 계정을 열고 키 탭으로 이동한 뒤 새 키 만들기 → 새 키 → JSON을 선택합니다. 파일은 한 번만 다운로드되며 이후에는 다시 받을 수 없습니다.

4. Search Console에서 속성을 열고 설정 → 사용자 및 권한 → 사용자 추가로 이동해 서비스 계정 이메일주소(name@project-id.iam.gserviceaccount.com)를 붙여넣고 권한으로 부여합니다:

   • 읽기 도구(analytics, sitemaps, URL 검사)에는 제한됨 또는 전체

   • submit_sitemap 및 delete_sitemap에는 전체

5. 서버가 접근해야 하는 모든 속성에 대해 4단계를 반복합니다 — 서비스 계정은 속성 소유권을 직접 확인할 수 없기 때문입니다.

6. 다운로드한 JSON 파일을 가리키도록 GOOGLE_SERVICE_ACCOUNT_KEY_PATH를 설정합니다.

JSON 키는 비밀번호처럼 다루세요. 부여된 권한을 그대로 가지며, 앞에는 2차 인증이 없습니다. 저장소 외부에 보관하고 chmod 600 적용을 고려하세요.

구성

속성은 https://example.com/ 같은 URL 접두 크 속성(프로토콜 및 끝 슬래시가 중요함 — https://example.com/과 http://example.com/은 서로 다른 속성) 또는 sc-domain:example.com 같은 도메인 속성으로 확인 속성이 Search Console에 추가되었던 형태를 사용하세요. 정확한 문자열은 list_sites로 확인할 수 있습니다.

Claude Code와 함께 사용하기

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@orellbuehler/search-console-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json",
        "GOOGLE_SEARCH_CONSOLE_SITE_URL": "https://example.com/"
      }
    }
  }
}

예시 프롬프트

• "이번 달 최고의 검색 쿼리는 무엇인가요?"

• "Google에서 클릭 수가 가장 많은 페이지는 어디인가요? 지난 28일과 비교하면 어떻게 달라졌나요?"

• "'pricing'이 포함된 쿼리 중 10위보다 아래 순위인 것들을 보여주세요 — 빠르게 개선 가능한 후보입니다."

• "우리 트래픽 중 모바일 대 데스크톱의 비율은 어떻게 되나요?"

• "지난 3개월 동안의 일별 클릭 수와 노출 수를 그래프로 그려주세요."

• "노출은 있는 데 클릭이 거의 없는 국가는 어디인가요?"

• "https://example.com/blog/launch가 색인되어 있는지 확인해 줄래요? 그렇지 않다면 이유도요."

• "사이트맵 정보를 알려주고 오류나 경고가 있는지 알려주세요."

• "어제 사이트 구조를 변경한 후 사이트맵을 다시 제출하세요."

• "'mcp server'로 순위가 겹치는(경쟁하는) 페이지를 알려주세요."

• "이번 분기에 Discover 트래픽과 일반 웹 검색 트래픽을 비교해 주세요."

도구

검색 분석

사이트맵

사이트

URL 검사

주의 사항 및 유의점

• 성과 데이터는 ~2–3일 정도 지연됩니다. 사용의 도구들의 기본 날짜 범위는 3일 전까지로 설정되어 있습니다. data_state: "all"는 최신이지만 불완전할 수 있는 데이터를 포함합니다.

• 16개월 보관 기간. 그보다 이전의 쿼리는 행을 반환되지 않습니다.

• 개인정보 보호 필터링. 희귀한 쿼리의 행은 나타나지 않으므로 쿼리별 행을 합산하면 실제 합계보다 작을 수 있습니다. 정확한 합계가 필요하면 차원 없이 조회하세요.

• 호출당 25,000행 제한. start_row로 페이지를 나누세요. row_limit보다 적은 행이 반환되면 마지막 페이지입니다.

• URL 검사 할당량은 속성당 하루 약 2,000회, 분당 600회입니다 — 대량 검사가 아닌 선택적으로 조회하세요.

• hour 차원은 data_state: "hourly_all"이 필요하며 최근 ~10일분만 덮습니다.

• 검색 데이터는 LLM으로 전달됩니다. 도구가 반환하는 모든 것이 모델 컨텍스트가 됩니다. 데이터가 환경을 떠나면 안 되는 속성은 연결하지 마세요.

개발

npm install
npm run build         # tsc -p tsconfig.build.json -> dist/
npm test              # vitest run
npm run lint          # eslint src
npm run typecheck     # tsc --noEmit
npm run format        # prettier --write .

빌드된 서버를 실제 속성에서 스모크 테스트해 보세요:

GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
npx @modelcontextprotocol/inspector node dist/index.js

CI / 릴리스

CI는 Node 20 및 22에서 format:check, lint, typecheck, test, build를 실행합니다. 배포는 npm의 신뢰 기반 퍼블리싱(OIDC, 토큰 없음)을 통해 GitHub 릴리스로 진행됩니다:

npm version patch
git push --follow-tags
gh release create "v$(node -p "require('./package.json').version")" --generate-notes

라이센스

MIT © Orell Bühler