Claude Code에 Google Search Console MCP를 추가하고, OAuth 토큰 만료를 해결한 경험

들어가며

이전에 Google Analytics MCP를 Claude Code에 연동하는 글을 작성한 적이 있습니다. GA4 데이터를 터미널에서 자연어로 분석할 수 있다는 점이 꽤 만족스러웠고, 한동안 잘 사용해왔습니다.

그러다 블로그의 검색 성과를 종합적으로 분석하고 싶다는 생각이 들었습니다. GA4만으로는 '사이트에 들어온 후' 행동만 볼 수 있을 뿐, '검색에서 어떻게 노출되고 클릭되는지'는 알 수 없었기 때문입니다. 그래서 Google Search Console(GSC) MCP를 추가로 연동하기로 했습니다.

그런데 이 과정에서 예상치 못한 문제들을 만났습니다. OAuth 토큰 만료, quota project 설정 오류 같은 것들입니다. 이 글에서는 설치 방법보다는 실전에서 마주친 문제들과 해결 과정에 초점을 맞추어 정리하겠습니다.

GA4와 GSC, 왜 둘 다 필요한가

두 도구는 분석하는 영역이 다릅니다.

• GA4: 사용자가 사이트에 들어온 이후의 행동 — 세션, 페이지뷰, 이탈률, 체류 시간
• GSC: 사용자가 사이트에 들어오기 전의 데이터 — 검색 노출수, 클릭수, 평균 게재순위, 검색 쿼리

예를 들어, "nestjs grafana"라는 검색어에서 내 글이 평균 2위로 노출되고 있다는 사실은 GSC에서만 확인할 수 있습니다. GA4에서는 해당 방문자가 어떤 검색어로 들어왔는지 알 수 없습니다.

블로그를 운영하면서 "어떤 키워드를 강화해야 하는지", "어떤 글이 노출은 되지만 클릭이 안 되는지" 같은 질문에 답하려면, 두 데이터를 함께 봐야 합니다. Claude Code에서 두 MCP를 모두 연동해두면 이런 질문을 자연어로 던질 수 있게 됩니다.

GSC MCP 설정

GSC MCP는 GA4 MCP와 같은 인증 방식을 사용합니다. gcloud CLI의 ADC(Application Default Credentials)를 통해 OAuth 토큰으로 인증합니다.

~/.claude.json의 mcpServers 섹션에 다음을 추가합니다:

{
  "google-search-console": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/gsc-mcp-server"],
    "env": {
      "GOOGLE_APPLICATION_CREDENTIALS": "/Users/[사용자명]/.config/gcloud/application_default_credentials.json"
    }
  }
}

GA4는 pipx run analytics-mcp를 사용하고, GSC는 npx @anthropic/gsc-mcp-server를 사용합니다. 패키지 관리자가 다르지만, 인증 파일은 동일한 ADC JSON을 바라봅니다. 즉, 하나의 gcloud 인증으로 두 MCP 서버가 모두 동작합니다.

실전에서 만난 문제들

문제 1: OAuth 토큰 만료 — invalid_grant

GA4 MCP를 잘 사용하다가 어느 날 갑자기 이런 에러가 발생했습니다:

Error: invalid_grant: Token has been expired or revoked

ADC 토큰은 영구적이지 않습니다. Google OAuth 토큰은 일정 기간이 지나거나 보안 이벤트가 발생하면 만료됩니다. 특히 개발 환경에서 사용하는 ADC 토큰은 별도의 자동 갱신 메커니즘이 없기 때문에, 수동으로 다시 로그인해야 합니다.

해결은 간단합니다:

gcloud auth application-default login

이 명령어를 실행하면 브라우저가 열리면서 Google 계정으로 다시 인증하게 되고, ~/.config/gcloud/application_default_credentials.json 파일이 갱신됩니다. 갱신 후에는 Claude Code를 재시작할 필요 없이 바로 MCP가 동작합니다.

문제 2: Quota Project 설정

gcloud 인증까지 마쳤는데, GA4 MCP에서 또 다른 에러가 발생했습니다:

403 SERVICE_DISABLED: Google Analytics API has not been enabled

이 에러 메시지는 오해를 불러일으킵니다. API가 비활성화되어서가 아니라, quota project가 설정되지 않아서 발생하는 경우가 많습니다. ADC 토큰에 어떤 프로젝트의 할당량을 사용할지 명시해줘야 합니다:

gcloud auth application-default set-quota-project [프로젝트-ID]

이 명령어는 ADC JSON 파일에 quota_project_id 필드를 추가합니다. 한 번 설정하면 토큰을 갱신해도 유지되는 경우가 많지만, 새로 로그인할 때 누락될 수 있으므로 기억해두는 것이 좋습니다.

ADC 토큰 관리 정리

여러 번의 시행착오를 거치면서 ADC 토큰 관리에 대한 나름의 루틴이 생겼습니다.

# 토큰 만료 시 갱신 순서
1. gcloud auth application-default login
2. gcloud auth application-default set-quota-project [프로젝트-ID]
3. Claude Code에서 MCP 도구 호출로 확인

몇 가지 알아두면 좋은 점들입니다:

• 토큰 갱신 후 Claude Code 재시작은 불필요합니다. MCP 서버가 매 호출마다 ADC 파일을 읽기 때문에, 파일만 갱신되면 바로 동작합니다.
• GA4와 GSC가 같은 ADC 파일을 사용합니다. 한 번 갱신하면 두 MCP 서버 모두 정상화됩니다.
• 토큰 만료 주기는 일정하지 않습니다. 보통 몇 주에서 한두 달 사이에 만료되는데, Google 계정의 보안 설정이나 비밀번호 변경 등에 의해 더 빨리 만료될 수 있습니다.

GSC + GA4 데이터를 결합해서 분석하기

두 MCP를 모두 연동한 후의 가장 큰 이점은, Claude Code에서 검색 노출부터 사이트 내 행동까지 전체 퍼널을 한 번에 분석할 수 있다는 점입니다.

예를 들어 이런 질문이 가능합니다:

"GSC에서 노출수 대비 클릭률이 낮은 페이지를 찾아주고,
해당 페이지의 GA4 이탈률도 함께 분석해줘"

실제로 저는 블로그 콘텐츠 전략을 검토할 때, GSC로 검색 키워드와 게재순위를 확인하고, GA4로 유입 경로와 사용자 행동을 확인한 뒤, MongoDB에서 글 메타데이터를 조회하는 방식으로 세 가지 데이터 소스를 결합한 분석을 Claude Code 안에서 수행했습니다.

이 분석을 통해 "기술 블로그에 여행 콘텐츠를 추가하는 것이 SEO에 불리하다"는 데이터 기반의 결론을 내릴 수 있었습니다. GA4 단독으로는 불가능했을 분석입니다.

마치며

처음에는 GSC MCP 하나만 추가하면 될 줄 알았습니다. 그런데 토큰 만료, quota project 설정까지 예상보다 몇 단계가 더 있었습니다.

돌이켜보면 각각의 문제는 크지 않았습니다. 하지만 에러 메시지만 보고는 원인을 파악하기 어려운 것들이 많았습니다. 특히 403 SERVICE_DISABLED가 실제로는 quota project 미설정 때문이라는 것은, 직접 겪어봐야 알 수 있는 부분이었습니다.

GA4 MCP 연동 방법은 이전 글에서 다루었으니, 이 글이 운영 과정에서 마주치는 실전 문제들을 해결하는 데 도움이 되었으면 합니다.