gsc-mcp-connector

자체 호스팅 Google Search Console MCP 서버로, 15분 안에 Cloudflare Workers에 배포할 수 있습니다. ChatGPT, Claude 또는 MCP를 지원하는 모든 클라이언트에 연결하여 자연어로 GSC 데이터를 조회하세요.

제공 기능

배포 후, AI 어시스턴트에 4가지 도구를 제공하는 개인 MCP 엔드포인트를 사용할 수 있습니다:

• list_sites — 인증된 사용자가 접근 가능한 모든 속성 확인

• query_search_analytics — 클릭수, 노출수, CTR, 순위를 쿼리/페이지/국가/기기/검색 형태/날짜별로 필터링 가능

• inspect_url — 전체 URL 검사 API 결과 (색인 상태, 표준 URL, 모바일, AMP)

• list_sitemaps — 제출된 모든 사이트맵과 처리 상태 확인

"지난 28일과 그 이전 28일 사이에 클릭 손실이 가장 큰 상위 50개 쿼리는 무엇인가요?"라고 물으면 어시스턴트가 데이터를 가져오고, 차이를 계산하며, 분석을 작성합니다. 더 이상 SQL 내보내기가 필요 없습니다.

Related MCP server: gsc-mcp-connector

작동 방식

ChatGPT/Claude  ──OAuth──▶  Your Worker  ──OAuth──▶  Google
                                 │
                                 └─ holds your Google refresh_token
                                    (encrypted, in OAuth grant props)

두 가지 OAuth 체인:

1. MCP 클라이언트 → Worker: ChatGPT/Claude가 Worker에 대해 OAuth 2.1 + PKCE를 수행합니다. 로그인 UI는 배포 시 설정한 정적 "액세스 키"(커넥터 게이트)를 요청합니다.

2. Worker → Google: 액세스 키 확인 후, 사용자는 Google 동의 화면으로 리디렉션되어 webmasters.readonly 권한을 부여합니다. 결과 리프레시 토큰은 OAuth 승인에 저장되며, 도구 호출 시마다 Worker가 새 액세스 토큰을 갱신하여 GSC를 호출합니다.

사용자의 Google 계정이 액세스를 제어합니다 — 서비스 계정, GSC 사용자 관리, 권한 전파 지연이 필요 없습니다.

사전 요구사항

Cloudflare Workers 무료 요금제(일 10만 건 요청)는 개인 SEO 사용에 충분합니다. 유료 Cloudflare 요금제 불필요.

빠른 시작 (~15분)

1. Worker 배포

이 README 상단의 Deploy to Cloudflare 버튼을 클릭하세요. Cloudflare가 저장소를 계정에 복제하고, 종속성을 설치하며, https://gsc-mcp-connector.<your-subdomain>.workers.dev 형식의 공개 URL을 제공합니다.

참고: 이 단계에서 MCP_BEARER_TOKEN, GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET을 입력하라는 메시지가 표시됩니다. 아직 Google 정보가 없으므로 MCP_BEARER_TOKEN에는 임의의 16진수 문자열을 입력하고(나중에 변경 가능), 두 Google 필드에는 아무 내용이나 붙여넣으세요. 4단계에서 올바르게 설정합니다.

버튼을 사용하지 않으려면 저장소를 로컬에 클론하고, npm install을 실행한 후 npx wrangler deploy를 실행하세요.

배포 후 Worker URL을 기록해 두세요. 3단계와 5단계에서 필요합니다.

2. 커넥터 액세스 키 생성

Google OAuth 전 게이트로 사용되는 정적 임의 문자열입니다. 커넥터를 사용하는 모든 사람은 로그인 UI에 이 문자열을 붙여넣어야 합니다.

openssl rand -hex 32

출력값을 저장하세요 — 비밀로 설정하고 ChatGPT/Claude에서 사용합니다.

3. Google Cloud 설정 (OAuth 클라이언트)

docs/SETUP_GCP.md의 단계별 가이드를 따르세요. 승인된 리디렉션 URI에 1단계의 Worker URL을 사용하세요. 클라이언트 ID와 클라이언트 시크릿을 받게 됩니다.

처음에는 가장 오래 걸리는 단계(~10분)이지만 한 번만 수행하면 됩니다.

4. Worker 비밀 설정

npx wrangler secret put MCP_BEARER_TOKEN
# paste the value from step 2

npx wrangler secret put GOOGLE_OAUTH_CLIENT_ID
# paste the Client ID from step 3

npx wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET
# paste the Client Secret from step 3

또는 Cloudflare 대시보드를 통해: Workers & Pages → 해당 worker → Settings → Variables and Secrets → 각 항목을 Secret 유형으로 추가하세요.

팁 — Windows 인코딩 문제: 파일 내용을 파이프로 전달할 때(예: Get-Content | wrangler secret put) 해당 파일에 UTF-8 BOM이 있으면 BOM이 비밀값에 포함되어 JSON 파싱이 깨집니다. Cloudflare 대시보드 또는 대화형 wrangler secret put(프롬프트에 붙여넣기)을 사용하면 이 문제를 완전히 피할 수 있습니다.

5. ChatGPT에 연결 (Plus/Pro/Team)

ChatGPT → Settings → Connectors → Add custom connector:

• Name: gsc

• MCP Server URL: https://YOUR-WORKER-URL/mcp (/mcp로 끝나야 함)

• Authentication: OAuth

• "I understand and want to continue" 체크

• Create

Worker의 로그인 UI가 포함된 팝업이 열립니다. MCP_BEARER_TOKEN을 붙여넣고 → Continue with Google 클릭 → Google에서 로그인(GSC 속성을 소유한 계정 사용) 및 webmasters.readonly 권한 부여 요청 → ChatGPT로 리디렉션되며 커넥터가 활성화됩니다.

새 채팅에서 도구 모음의 gsc 커넥터를 활성화한 후, "내 Google Search Console 사이트를 나열해줘"라고 물어보세요. 속성이 표시되어야 합니다.

6. (선택 사항) Claude.ai에 연결 (Pro/Team)

Settings → Integrations → Add custom integration → 동일한 URL, 동일한 흐름.

로컬 개발

git clone https://github.com/JuJu78/gsc-mcp-connector
cd gsc-mcp-connector
npm install
cp .dev.vars.example .dev.vars
# edit .dev.vars with your real Client ID + Client Secret + bearer token
npx wrangler dev

개발 서버는 http://localhost:8787에서 실행됩니다. Google의 리디렉션 URI는 HTTPS를 요구하므로 로컬 개발에서는 Google OAuth 흐름을 완전히 완료할 수 없습니다. 실제 종단 간 테스트를 위해서는 Cloudflare에 배포하고 workers.dev URL로 테스트하세요.

제한사항

• 읽기 전용. 쓰기 작업(사이트맵 제출, 색인 요청)은 의도적으로 제외되었습니다 — LLM 컨텍스트에서 위험합니다. 필요하다면 PR을 열어주세요.

• 단일 테넌트 설계. 한 명의 운영자가 배포하고, 하나의 베어러 토큰이 커넥터를 제어하며, 액세스는 Google OAuth를 완료한 사람에게 바인딩됩니다. 멀티 사용자 SaaS 스타일은 범위를 벗어납니다.

• OAuth 동의 테스트 모드는 100명의 테스트 사용자로 제한됩니다(개인/팀 사용에 충분). 광범위한 배포를 위해서는 앱을 Google 검증에 제출해야 합니다(webmasters.readonly는 "민감한" 범위로, 수동 검토 필요).

• GSC API 할당량 — 프로젝트당 분당 1200개 쿼리, 일 3만 개. 대화형 사용에 충분합니다.

• 날짜 범위 — GSC는 최근 16개월을 반환합니다. 이전 날짜는 오류가 발생합니다.

문제 해결

기술 스택

• Cloudflare Workers + Durable Objects (agents SDK ≥0.12 사용)

• @cloudflare/workers-oauth-provider — OAuth 2.1 + DCR + PKCE용

• @modelcontextprotocol/sdk — 도구 정의용

• KV 네임스페이스 OAUTH_KV — OAuth 상태용

• Web Crypto API를 통해 기본 서명된 Google OAuth 2.0 흐름 (Node 종속성 없음)

크레딧

Julien Gourdon이 제작 — 검색과 AI의 교차점을 탐구하는 SEO 컨설턴트.

라이선스

MIT — LICENSE 참조.