gsc-mcp-connector

자체 호스팅 Google Search Console MCP 서버로, Cloudflare Workers에 15분 안에 배포할 수 있습니다. 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개 쿼리, 하루 30,000개. 대화형 사용에 충분합니다.

• 날짜 범위 — 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 상태 저장

• Google OAuth 2.0 흐름은 Web Crypto API로 네이티브 서명 (Node 종속성 없음)

크레딧

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

라이선스

MIT — LICENSE 참조