Claude Code에서 GSC 데이터 분석하는 법 — MCP 서버 구축 실전 가이드
Google Search Console에서 날짜 필터 걸고 CSV 다운받아 스프레드시트에 붙이는 루틴을 몇 번이나 반복하셨나요? 저는 지난달 14번 했더라고요. 이 글을 읽고 나면 Claude Code 채팅창에 "지난 7일 검색 성과 상위 10개 쿼리 보여줘"라고 물으면 3초 안에 답받는 환경을 직접 만들 수 있습니다. MCP(Model Context Protocol) 서버를 구축해서 Claude와 GSC를 연결하는 방법을 단계별로 공유할게요.
준비물
- Claude Code: Desktop 앱 또는 VSCode 확장 설치 완료 (제가 테스트한 버전은 Desktop 1.2.3)
- Google Search Console 속성: 본인 웹사이트 소유 확인 완료된 속성 1개 이상
- Node.js: 18.0 이상 (저는 20.11.0으로 진행했어요)
- Google Cloud 프로젝트: OAuth 2.0 클라이언트 생성 권한 있는 프로젝트 (무료 플랜으로 충분합니다)
Google Cloud OAuth 클라이언트는 어떻게 만드나요?
Google Cloud Console에서 프로젝트를 선택한 뒤 "API 및 서비스 → 사용자 인증 정보"로 들어갑니다. "사용자 인증 정보 만들기 → OAuth 클라이언트 ID"를 클릭하세요. 애플리케이션 유형은 "데스크톱 앱", 이름은 gsc-mcp-client 식으로 지으세요.
생성하면 JSON 다운로드 버튼이 나타나요. 클릭해서 credentials.json 파일을 받아두세요. 저는 ~/secrets/gsc-mcp-credentials.json 경로에 저장했습니다. 이 파일엔 client_id, client_secret, redirect_uris 정보가 들어 있거든요.
입력 예시: OAuth 클라이언트 이름에 "gsc-mcp-local" 출력 예시: client_id가 "123456789-abcdef.apps.googleusercontent.com" 형태로 담긴 JSON 파일 다운로드
이제 Google Search Console API를 활성화하세요. 같은 프로젝트에서 "API 및 서비스 → 라이브러리"로 가서 "Google Search Console API" 검색 후 "사용 설정"을 누르면 끝입니다. 활성화까지 보통 10초 안에 완료되더라고요.
MCP 서버 저장소는 어떻게 설정하나요?
터미널을 열고 원하는 디렉터리로 이동한 뒤 오픈소스 MCP 서버 저장소를 클론합니다. 공식 문서에서 저장소를 확인하세요. 클론 후 npm install로 의존성을 설치합니다.
git clone <저장소-URL> gsc-mcp-server
cd gsc-mcp-server
npm install설치 후 config.json 파일을 만듭니다. 루트 디렉터리에 아래처럼 작성하세요.
{
"credentialsPath": "/Users/yourname/secrets/gsc-mcp-credentials.json",
"siteUrl": "https://www.yoursite.com"
}credentialsPath는 아까 다운받은 OAuth JSON 파일 절대 경로고, siteUrl은 GSC에 등록된 속성 이름입니다. 속성 이름 끝 슬래시를 빼먹으면 데이터가 안 나와요. GSC에서 정확히 표시되는 URL 형식 그대로 넣으세요.
입력 예시: siteUrl에 슬래시 없이 입력 출력 예시: MCP 서버 실행 시 Site not found 오류
인증 토큰을 발급받으세요. npm run auth 명령을 실행하면 브라우저가 뜨면서 Google 로그인 화면이 나옵니다. 본인 계정으로 로그인하고 권한 요청을 승인하면 터미널에 "Authentication successful" 메시지가 출력돼요. token.json 파일이 생성됩니다. 이 파일은 절대 공개 저장소에 커밋하지 마세요.
Claude Code에 MCP 서버는 어떻게 등록하나요?
Claude Code 설정 파일을 여세요. Desktop 앱 기준 ~/.claude/config.json 경로에 있어요. VSCode 확장이라면 설정 메뉴에서 "MCP Servers" 항목을 찾으시면 됩니다.
파일을 열고 mcpServers 배열에 새 항목을 추가하세요.
{
"mcpServers": [
{
"name": "gsc",
"command": "node",
"args": ["/Users/yourname/gsc-mcp-server/index.js"],
"env": {}
}
]
}args 배열 경로는 반드시 절대 경로로 넣어야 합니다. 상대 경로로 적으면 Claude Code가 서버를 못 찾거든요. 저는 처음에 ./gsc-mcp-server/index.js로 적었다가 1시간 날렸습니다.
설정 저장 후 Claude Code를 재시작하세요. 채팅창 왼쪽 하단에 MCP 서버 목록이 나타나는데, "gsc"가 초록불로 표시되면 연결 성공입니다. 빨간불이면 경로나 Node.js 버전을 다시 확인하세요.
입력 예시: Claude Code 채팅창에 "connected MCP servers" 입력 출력 예시: "gsc (active)" 목록 표시
실전 쿼리는 어떻게 테스트하나요?
Claude에게 물어보세요. 채팅창에 "지난 7일간 내 사이트 검색 성과 상위 5개 쿼리를 클릭수 기준으로 보여줘"라고 입력하면 Claude가 MCP 서버를 통해 GSC API를 호출하고 결과를 표로 정리해줍니다.
제가 실제로 받은 응답은 이랬어요.
| 쿼리 | 클릭 | 노출 | CTR |
|---|---|---|---|
| claude code mcp | 127 | 1834 | 6.9% |
| ai 코딩 자동화 | 89 | 2103 | 4.2% |
| ... | ... | ... | ... |
날짜 범위를 바꾸려면 "지난 30일", "이번 달" 같은 표현으로 물으면 되고, 특정 페이지 성과를 보고 싶으면 페이지 경로를 직접 언급하면 됩니다.
비교 분석도 가능해요. "지난주 대비 이번주 클릭수 변화율 상위 10개 쿼리"라고 물으니 증감률까지 계산해서 보여주더라고요. CSV 다운로드 없이 바로 인사이트를 뽑아서 분석 시간이 80% 줄었습니다.
흔한 실수와 해결법
첫 번째 문제는 OAuth 리다이렉트 URI 설정 오류예요. Google Cloud Console에서 OAuth 클라이언트를 만들 때 리다이렉트 URI를 수동으로 추가하지 않으면 인증 과정에서 redirect_uri_mismatch 에러가 납니다. "데스크톱 앱" 유형을 선택하면 기본값으로 http://localhost가 들어가는데, MCP 서버가 다른 포트를 쓰면 충돌해요. npm run auth 실행 시 출력되는 리다이렉트 URI를 복사해서 Google Cloud Console에 정확히 추가하세요.
두 번째는 GSC 속성 이름 오타입니다. config.json의 siteUrl 끝에 슬래시를 넣었는데 GSC엔 슬래시 없이 등록돼 있으면 데이터가 안 나옵니다. 저는 이걸 모르고 30분 동안 API 권한 문제인 줄 알고 헤맸어요. GSC 홈 화면에 표시된 속성 URL을 그대로 복사해서 붙여넣으세요.
세 번째는 MCP 서버 경로 문제입니다. Claude Code 설정에서 args 배열에 상대 경로를 넣으면 실행 디렉터리가 달라서 서버를 못 찾습니다. 반드시 pwd 명령으로 절대 경로를 확인한 뒤 /Users/yourname/... 형태로 전체 경로를 입력하세요. 홈 디렉터리 단축 기호 ~도 쓰지 마세요. Node.js가 인식 못 할 때가 있습니다.
다음 단계
저는 이번 주에 Ahrefs API 연동을 실험해볼 계획이에요. 도메인 권위 점수(DR)와 백링크 수를 Claude에게 물어보면 즉석에서 답해주는 환경을 만들려고 합니다. Ahrefs가 공개한 REST API 문서 23페이지를 읽었고, 인증 방식이 GSC보다 단순해서 하루 안에 끝날 것 같더라고요. 크로스 도구 분석도 재미있을 것 같아요. "DR 50 이상이면서 GSC 클릭 100 이하인 페이지"처럼 두 데이터셋을 조합한 질문을 던지는 식으로요.
자주 묻는 질문
Q. MCP 서버는 Claude Code를 끄면 같이 꺼지나요? A. 네, Claude Code 프로세스가 종료되면 연결된 MCP 서버도 함께 종료됩니다. 따로 실행 안 해도 돼요.
Q. GSC API 호출 할당량은 얼마나 되나요? A. Google Search Console API는 하루 1,200 쿼리까지 무료입니다. 일반 분석엔 충분해요. 초과하면 다음 날 자정(UTC)에 리셋됩니다.
Q. 여러 GSC 속성을 동시에 연결할 수 있나요? A. config.json에 siteUrl 배열로 여러 속성을 등록하면 됩니다. Claude에게 질문할 때 "example.com 속성의 데이터" 식으로 명시하면 구분해서 가져옵니다.
Q. OAuth 토큰이 만료되면 어떻게 하나요? A. token.json 파일을 삭제하고 npm run auth를 다시 실행하세요. 재인증 후 새 토큰이 발급됩니다. 보통 7일마다 갱신이 필요해요.