mcp-google-gsc

Google Search Console용 MCP 서버 -- Claude를 통한 검색 분석, URL 검사, 사이트 관리.

기능

• 검색 분석 -- 유연한 차원 필터(쿼리, 페이지, 기기, 국가, 날짜)로 클릭수, 노출수, CTR, 순위를 조회합니다

• URL 검사 -- 모든 URL의 색인 상태, 모바일 사용성, 리치 결과를 확인합니다

• 사이트 목록 -- 인증된 계정(OAuth 사용자 또는 서비스 계정)에서 액세스할 수 있는 모든 검증된 Search Console 속성을 나열합니다

• 다중 클라이언트 지원 -- 디렉터리별 구성 매핑으로 여러 GSC 속성을 관리합니다

Related MCP server: Google Search Console MCP Server

설치

npm에서

npm install mcp-google-gsc

소스에서

git clone https://github.com/mharnett/mcp-search-console.git
cd mcp-google-gsc
npm install
npm run build

구성

보안: .mcp.json 파일을 공유하거나 git에 커밋하지 마세요 -- API 자격 증명이 포함될 수 있습니다. .gitignore에 .mcp.json을 추가하세요.

mcp-gsc는 두 가지 인증 모드를 지원합니다. 설정에 맞는 것을 선택하세요. 어떤 모드도 하드코딩된 머신 로컬 경로에 파일이 필요하지 않습니다 -- 자격 증명은 환경 변수(또는 직접 만든 config.json)에서 가져옵니다.

어떤 모드를 사용할까요:

• 서비스 계정 (모드 B) -- 무인 / 서버 / 헤드리스 사용에 권장. 서비스 계정은 만료되거나 재동의가 필요한 대화형 로그인이 없으므로 항상 실행되는 배포에 적합합니다. 유일한 설정 요구 사항은 서비스 계정의 이메일이 쿼리하려는 각 Search Console 속성에 액세스 권한이 부여되어야 한다는 것입니다 (모드 B 참조).

• 사용자 OAuth (모드 A) -- 개인 / 대화형 사용용. 자신의 Google 로그인으로 인증하려는 경우에 사용합니다.

둘 다 구성된 경우의 우선순위: 서비스 계정 키 파일이 명시적으로 설정된 경우(GOOGLE_APPLICATION_CREDENTIALS 또는 config.json의 credentials_file), OAuth 리프레시 토큰이나 저장된 OAuth 자격 증명보다 우선합니다. 둘 다 구성되지 않은 경우, 서버는 조용히 추측하는 대신 시작 시 온보딩 메시지와 함께 명시적으로 실패합니다 -- 머신 로컬 기본값이 없고 모드 간 자동 장애 조치(failover)도 없습니다.

모드 A: 사용자 OAuth (자체 Google 계정 사용)

Search Console 액세스 권한이 있는 계정으로 인증하려는 경우 사용합니다. 개인 / 대화형 사용에 가장 적합합니다.

1. Google Cloud Console에서 데스크톱 앱 유형의 OAuth 2.0 클라이언트 ID를 만들고 Search Console API를 사용 설정합니다. (데스크톱 앱 클라이언트의 경우 Google은 모든 http://localhost 루프백 리디렉션을 허용하므로 포트를 사전 등록할 필요가 없습니다.)

2. 클라이언트 자격 증명을 내보냅니다:

   export GOOGLE_GSC_CLIENT_ID=...apps.googleusercontent.com
   export GOOGLE_GSC_CLIENT_SECRET=...

3. 리프레시 토큰을 발급합니다 (브라우저가 열리고 PKCE + access_type=offline 사용):

   node get-refresh-token.cjs

   이 명령의 stdout을 공유 로그로 리디렉션하지 마세요 -- 설계상 리프레시 토큰을 stdout으로 출력합니다.

4. 출력된 줄을 환경에 복사합니다:

   export GOOGLE_GSC_REFRESH_TOKEN=...

서버는 런타임 시 환경에서 GOOGLE_GSC_CLIENT_ID, GOOGLE_GSC_CLIENT_SECRET, GOOGLE_GSC_REFRESH_TOKEN을 읽습니다.

또는 안내 도우미 npx mcp-gsc-auth를 실행할 수 있습니다. 이 도우미는 동일한 PKCE OAuth 흐름을 수행하고, 기본 Search Console 속성을 선택할 수 있게 하며, 결과를 사용자별 자격 증명 파일에 기록합니다.

모드 B: 서비스 계정 (무인 / 서버 사용에 권장)

서버 / 헤드리스 / 항상 실행되는 환경에서 사용하세요 -- 대화형 로그인을 완료하거나 갱신할 사람이 없는 경우 권장되는 경로입니다.

1. Search Console API 액세스 권한이 있는 Google Cloud 서비스 계정을 만들고 JSON 키 파일을 다운로드합니다.

2. 쿼리하려는 각 Search Console 속성에 서비스 계정의 이메일 액세스 권한을 부여합니다 (Search Console에서 사용자로 추가). 속성에 이 권한이 없으면 서비스 계정은 인증할 수 있지만 사이트가 표시되지 않습니다.

3. 환경 변수를 통해 키 파일을 서버에 지정합니다 (하드코딩된 경로 없음):

   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json

OAuth 범위

두 모드 모두 단일 읽기 전용 범위를 요청합니다: https://www.googleapis.com/auth/webmasters.readonly. 네 가지 도구 모두 읽기 전용입니다 -- 쓰기 작업이 없으므로 서버는 읽기/쓰기 액세스를 요청하지 않습니다.

범위는 config.json의 oauth.scope에 한 번 정의됩니다 (config.example.json 참조). OAuth 도우미와 런타임은 동일한 값을 읽으므로 서로 어긋나지 않습니다. config.json이 없는 경우(예: 새 설치), 커밋된 읽기 전용 기본값이 사용됩니다.

다중 클라이언트 구성 (선택 사항)

작업 디렉터리를 Search Console 속성에 매핑하려면 프로젝트 루트에 config.json을 만듭니다 (config.example.json 참조):

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/webmasters.readonly"
  },
  "clients": {
    "my-project": {
      "name": "My Project",
      "folder": "/path/to/project",
      "site_url": "https://example.com/"
    }
  }
}

사용법

Claude Code .mcp.json에 추가:

{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/path/to/mcp-gsc/dist/index.js"]
    }
  }
}

또는 전역으로 설치된 경우:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["mcp-google-gsc"]
    }
  }
}

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)에 추가합니다.

도구

gsc_search_analytics

차원 지원: query, page, device, country, date. equals, contains, notContains 같은 연산자로 모든 차원을 필터링할 수 있습니다. 날짜 범위는 기본적으로 최근 28일입니다.

gsc_inspection

속성 내 특정 URL의 색인 적용 범위, 크롤링 상태, 모바일 사용성 판정, 리치 결과 세부 정보를 반환합니다.

아키텍처

• 복원력 -- 모든 Google API 호출에 지수 백오프가 있는 재시도 및 회로 차단기 패턴을 위해 cockatiel 사용

• 로깅 -- 구성 가능한 로그 수준을 가진 pino를 통한 구조화된 로깅

• 응답 처리 -- MCP 전송 제한 내에 유지하기 위해 응답을 200KB로 자릅니다

라이선스

MIT -- LICENSE 참조.

Mark Harnett / drak-marketing 제작