gsc-ga4-mcp

Claude Code에 Google Search Console과 GA4에 대한 읽기 전용 액세스를 부여하는 작은 로컬 MCP 서버로, 두 데이터셋을 교차 조회하는 몇 가지 도구도 함께 제공합니다.

문제

AI 어시스턴트에서 SEO 작업을 한다는 것은 보통 Search Console에서 CSV를 내보내고, GA4에서 CSV를 또 내보내고, 두 파일을 채팅에 붙여넣고, 새 수치가 필요할 때마다 그 과정을 반복하는 것을 뜻합니다. 그리고 두 데이터셋은 절대 저절로 맞지 않습니다. Search Console은 노출수, 클릭수, CTR을 알고 있고, GA4는 세션, 참여도, 전환을 알고 있습니다. "트래픽은 받지만 그걸 낭비하는 페이지"를 알아내려면 URL 기준으로 두 데이터셋을 수동 조인해야 합니다.

Google은 Analytics용 공식 MCP 서버를 제공하지만, Search Console은 다루지 않습니다. 커뮤니티에 Search Console 서버도 있지만, 데이터가 클라이언트 소유라면 남의 서버를 신뢰하기보다 처음부터 끝까지 직접 살펴볼 수 있는 작은 래퍼를 실행하는 것이 낫습니다.

이 서버는 읽기 전용 범위만으로 Google 공식 API를 사용자 자신의 머신에서 직접 호출합니다.

Related MCP server: Google Search Console MCP Server

하는 일

stdio를 통해 제공되는 20개의 MCP 도구입니다.

Search Console

GA4

결합 분석

구성

project_mappings와 project_lookup은 프로젝트나 클라이언트 이름을 해당 GSC 속성 및 GA4 속성과 매핑하는 로컬 파일을 읽습니다. 따라서 properties/123456789을 기억하는 대신 "example.com에 대해 GSC와 GA4를 교차 조회해 줘"라고 말할 수 있습니다.

기술 스택

Node.js + TypeScript가 기본입니다. 서버에는 @modelcontextprotocol/sdk, 인증에는 google-auth-library, 도구 스키마에는 zod를 사용합니다. 별도 데이터베이스도, 호스팅 백엔드도, 텔레메트리도 없습니다 — 프로세스는 로컬에서 실행되며 Claude Code가 stdio로 파일을 실행합니다.

범위는 읽기 전용이며, 이것이 권한의 전부입니다:

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

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

자격 증명은 저장소 바깥, 기본적으로 ~/.config/gsc-ga4-mcp/에 있습니다.

설정

1.설치

git clone https://github.com/YOUR_USER/gsc-ga4-mcp.git
cd gsc-ga4-mcp
npm install
npm run build
mkdir -p ~/.config/gsc-ga4-mcp

2. API 지원하기

Google Cloud Console에서 프로젝트를 만들거나 선택한 뒤, 다음 API를 사용하도록 설정합니다:

• Google Search Console API

• Google Analytics Data API

• Google Analytics Admin API

3. OAuth 자격 증명 만들기

APIs & Services → OAuth consent screen에서 동의 화면을 구성합니다. 관리하는 속성이 하나의 Google Workspace에 몰려 있지 않다면 External(외부)을 사용하고, 앱이 테스트 중일 때 자신의 이메일을 테스트 사용자로 추가합니다.

APIs & Services → Credentials에서 OAuth Client ID를 Desktop app 유형으로 생성하고, JSON을 다운로드한 후 ~/.config/gsc-ga4-mcp/oauth-client.json에 저장합니다.

권한을 계정 단위로 분리하고 싶은 클라이언트 작업이라면 대신 서비스 계정을 사용하고, 각 GSC와 GA4 속성에 그 이메일을 읽기 권한으로 추가합니다. 그리고 GOOGLE_AUTH_MODE=service_account를 설정하고 GOOGLE_SERVICE_ACCOUNT_KEY_FILE에 열쇠 파일 경로를 지정합니다.

4. 구성

cp .env.example .env
cp projects.example.json ~/.config/gsc-ga4-mcp/projects.json

.env의 경로는 절대 경로여야 하며 ~는 확장되지 않습니다.

GOOGLE_AUTH_MODE=oauth
GOOGLE_OAUTH_CREDENTIALS_FILE=/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json
GOOGLE_TOKEN_PATH=/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json
GOOGLE_OAUTH_REDIRECT_URI=http://127.0.0.1:3000/oauth2callback
PROJECTS_CONFIG=/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json
MCP_DEFAULT_GSC_SITE=sc-domain:example.com
MCP_DEFAULT_GA4_PROPERTY=properties/123456789
MAX_ROWS=25000

프로젝트 매핑(projects.json):

{
  "projects": [
    {
      "name": "My Site",
      "client": "Internal",
      "domain": "example.com",
      "gscSiteUrl": "sc-domain:example.com",
      "ga4Property": "properties/123456789",
      "notes": "Replace with the real GA4 property ID."
    }
  ]
}

5. 인증

npm run auth

스크립트는 127.0.0.1:3000에 루프백 리스너를 띄우고 Google URL 하나를 출력합니다. 그 URL을 열고 읽기 전용 범위를 승인하면 토큰이 GOOGLE_TOKEN_PATH에 기록됩니다.

6. Claude Code에 등록하기

claude mcp add google-seo -- node /ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js
claude mcp list

또는 도구를 사용할 프로젝트에 .mcp.json을 커밋할 수도 있습니다 (참고: .mcp.example.json):

{
  "mcpServers": {
    "google-seo": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js"],
      "env": {
        "GOOGLE_AUTH_MODE": "oauth",
        "GOOGLE_OAUTH_CREDENTIALS_FILE": "/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json",
        "GOOGLE_TOKEN_PATH": "/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json",
        "PROJECTS_CONFIG": "/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json",
        "MCP_DEFAULT_GSC_SITE": "sc-domain:example.com",
        "MCP_DEFAULT_GA4_PROPERTY": "properties/123456789"
      }
    }
  }
}

경로와 기본 속성 기본값을 저장소에 보관하고 싶지 않다면 CLI 등록을 사용하세요.

Claude Code 사용 방법

간단한 언어로 요청하면 Claude가 필요한 도구를 선택합니다.

Use gsc_list_sites and ga4_list_properties. Give me a table of the GSC sites
and GA4 properties I can reach.

Analyse organic traffic for sc-domain:example.com over the last 90 days using
gsc_top_queries and gsc_top_pages.

Cross GSC and GA4 for example.com over the last 90 days. Find pages with high
impressions and low CTR, and rank the opportunities by likely impact.

Run seo_opportunity_report and group the output into quick wins, pages that
need a rewrite, and pages that miss search intent.

Inspect https://www.example.com/page/ with gsc_url_inspection and tell me
whether Google has it indexed.

운영 정보

• .env, token.json, projects.json 및 서비스 계정 키는 버전 관리에서 제외하세요. 함께 제공된 .gitignore에 이미 포함되어 있습니다.

• 클라이언트 분석 데이터는 기밀입니다. 클라이언트가 승인하지 않은 도구에 전체 출력을 붙여넣지 마세요.

• 고객과의 계약이 끝나면 토큰 또는 서비스 계정을 폐기하세요.

• MAX_ROWS는 응답 크기를 제한합니다. 응답이 다루기 부담스러우면 값을 낮추세요.

문제 해결

• Claude Code가 도구를 인식하지 못하는 경우. claude mcp list를 실행한 뒤 Claude Code에서 /mcp를 실행해 보세요.

• OAuth 토큰 오류. npm run auth를 다시 실행하고 GOOGLE_TOKEN_PATH가 절대 경로인지 확인하세요.

• access_denied. 앱이 테스트 중이면 OAuth 동의 화면에 자신의 이메일을 테스트 사용자로 추가하세요.

• GSC에서 도메인이 안 보이는 경우. 해당 정확한 도메인의 속성에 접근할 수 있어야 합니다. sc-domain:example.com과 https://www.example.com/은 서로 다른 속성입니다.

• GA4 속성이 안 보이는 경우. 사용자나 서비스 계정에 계정 또는 속성에 대한 최소한 뷰어(Viewer) 권한이 필요합니다.

• gsc_url_inspection 실패. inspectionUrl은 siteUrl 안에 있어야 하며, URL-prefix 속성은 /로 끝나야 합니다.

• GA4 측정항목 오류. GA4의 공식 dimension 및 metric 이름을 사용하세요. runReport는 그 밖의 이름은 거부합니다.

Reference

• Claude Code MCP를 참조하세요.

• Model Context Protocol

• Search Console API

• GA4 데이터 API

• Google Analytics Admin API

• Google OAuth 범위

라이센스

MIT 리미. LICENSE를 참조하세요.