SEO를 위한 Google Search Console MCP 서버

Google Search Console(GSC)을 AI 어시스턴트에 연결하는 Model Context Protocol(MCP) 서버로, 자연어 대화를 통해 SEO 데이터를 분석할 수 있습니다. Claude Desktop, Cursor, Codex CLI, Gemini CLI, Antigravity 및 기타 모든 MCP 호환 클라이언트에서 작동합니다.

설정 건너뛰고 더 많은 기능을 누리세요. 더 발전된 호스팅 버전 — 원클릭 로그인, GA4 도구 추가. Claude Desktop, Claude Code, Claude.ai, Codex, Cursor 및 모든 MCP 클라이언트에서 작동합니다. 100석 한정. → 고급 GSC MCP (호스팅)

새로운 소식

[0.3.3] — 2026년 7월

• mcp 2.0으로 인해 깨진 신규 설치 수정 — mcp[cli]<2.0.0으로 고정. mcp SDK 2.0.0(2026-07-28 출시)에서 mcp.server.fastmcp 모듈이 제거되어, 새로 uvx mcp-search-console을 설치할 때마다 ModuleNotFoundError: No module named 'mcp.server.fastmcp' 오류로 시작 시 충돌이 발생했습니다. 이제 새 설치 시 작동하는 1.x SDK로 해결됩니다 — --with "mcp<2" 우회 방법이 필요 없습니다.

[0.3.2] — 2026년 4월

• uvx용 OAuth 브라우저 흐름 수정 — macOS에서 MCP 하위 프로세스로 실행할 때 브라우저 로그인 창이 열리지 못하게 하던 isatty 블록을 제거했습니다. 이제 OAuth가 uvx에서 별도의 수동 터미널 실행 없이 바로 작동합니다.

• get_capabilities 도구 추가 — 이 도구를 호출하면 사용 가능한 전체 도구 목록과 현재 인증 상태를 한 번에 확인할 수 있습니다. AI 어시스턴트가 어떤 도구를 사용할 수 있는지 확실하지 않을 때 유용합니다.

• 더 나은 인증 오류 메시지 — 이제 모든 도구가 자격 증명이 없거나 만료되었을 때 정확히 무엇을 해야 하는지 알려줍니다.

Related MCP server: Google Search Console MCP Server

무엇을 할 수 있나요?

속성 관리

• 모든 GSC 속성을 한 곳에서 확인

• 검증 세부 정보 및 소유권 정보 확인

• 계정에서 속성 추가 또는 제거

검색 분석 및 보고

• 사이트에 방문자를 유입시키는 검색어 확인

• 노출수, 클릭수, 클릭률 추적

• 성과 추세 분석 및 기간 비교

• AI 어시스턴트가 생성한 차트로 데이터 시각화

URL 검사 및 색인 생성

• 특정 페이지의 색인 생성 문제 확인

• Google이 페이지를 마지막으로 크롤링한 시기 확인

• 여러 URL을 한 번에 검사하여 패턴 식별

사이트맵 관리

• 모든 사이트맵 및 상태 확인

• 새 사이트맵 제출

• 오류 또는 경고 확인

사용 가능한 도구

AI 어시스턴트에게 "get_capabilities 호출"을 요청하면 전체 20개 도구 목록을 확인할 수 있습니다.

시작하기

1단계 — Google API 자격 증명 설정

클라이언트를 구성하기 전에 자격 증명이 필요합니다. 다음 방법 중 하나를 선택하세요:

옵션 A — OAuth (권장 — 자신의 Google 계정 사용)

1. Google Cloud Console로 이동하여 프로젝트를 만들거나 선택합니다

2. Search Console API 사용 설정

3. 사용자 인증 정보로 이동 → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID

4. OAuth 동의 화면을 구성하고 데스크톱 앱을 선택한 후 만들기를 클릭합니다

5. JSON 파일을 다운로드하여 영구적인 위치에 저장합니다 (예: ~/Documents/client_secrets.json)

첫 사용 시 Google 계정으로 로그인하라는 브라우저 창이 열립니다. 이후에는 토큰이 저장되어 더 이상 브라우저 상호작용이 필요하지 않습니다.

옵션 B — 서비스 계정 (자동화 또는 팀 사용용)

1. Google Cloud Console로 이동하여 프로젝트를 만들거나 선택합니다

2. Search Console API 사용 설정

3. 사용자 인증 정보로 이동 → 사용자 인증 정보 만들기 → 서비스 계정

4. 키 탭으로 이동 → 키 추가 → 새 키 만들기 → JSON → 다운로드

5. 파일을 영구적인 위치에 저장합니다 (예: ~/Documents/service_account.json)

6. GSC 속성에 서비스 계정 이메일을 추가합니다: Search Console → 설정 → 사용자 및 권한 → 사용자 추가 → 전체 액세스

🎥 이 섹션의 단계별 설정 튜토리얼 시청하기

2026년 업데이트 — Google 자격 증명 설정부터 첫 번째 성공적인 쿼리까지 새로운 uvx 방법을 사용한 전체 설치 과정을 다룹니다.

2단계 — 설치

옵션 A — uvx (권장)

클론, Python 설치, 가상 환경이 필요 없습니다. uvx가 서버를 자동으로 다운로드하여 실행하고 최신 상태로 유지합니다.

uv 설치 — 터미널을 열고 세 가지 명령을 순서대로 실행합니다:

# 1. Download and install
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Activate in the current Terminal session
source $HOME/.local/bin/env

# 3. Make it permanent for all future sessions
echo 'source $HOME/.local/bin/env' >> ~/.zshrc

확인:

uv --version

세 가지 명령이 모두 필요한 이유는? 설치 프로그램이 uv를 ~/.local/bin에 넣지만, 이미 열려 있는 터미널 세션은 해당 폴더를 아직 인식하지 못합니다. 2단계는 즉시 활성화합니다. 3단계는 향후 모든 터미널 창에서 자동으로 사용할 수 있도록 보장합니다.

이제 AI 클라이언트를 구성합니다:

Claude Desktop

구성 파일: ~/Library/Application Support/Claude/claude_desktop_config.json

OAuth:

{
  "mcpServers": {
    "gscServer": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
      }
    }
  }
}

서비스 계정:

{
  "mcpServers": {
    "gscServer": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

Cursor

구성 파일: ~/.cursor/mcp.json

OAuth:

{
  "mcpServers": {
    "gscServer": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
      }
    }
  }
}

Codex CLI

구성 파일: ~/.codex/config.toml

OAuth:

[mcp_servers.gscServer]
command = "/FULL/PATH/TO/uvx"
args = ["mcp-search-console"]
enabled = true
env = { GSC_OAUTH_CLIENT_SECRETS_FILE = "/full/path/to/client_secrets.json" }

서비스 계정:

[mcp_servers.gscServer]
command = "/FULL/PATH/TO/uvx"
args = ["mcp-search-console"]
enabled = true
env = { GSC_CREDENTIALS_PATH = "/full/path/to/service_account.json", GSC_SKIP_OAUTH = "true" }

uvx 경로 찾기: macOS/Linux에서는 uv 설치 후 터미널에서 which uvx를 실행합니다 (일반적으로 /Users/사용자이름/.local/bin/uvx). Windows에서는 PowerShell에서 Get-Command uvx | Select-Object -ExpandProperty Source를 실행합니다 (또는 cmd에서 where uvx) — 보통 C:\Users\사용자이름\.local\bin\uvx.exe입니다. 위 구성에서 /FULL/PATH/TO/uvx를 해당 경로로 바꾸세요.

전체 경로가 필요한 이유는? Claude Desktop 및 Cursor와 같은 GUI 앱은 셸 구성(~/.zshrc)을 읽지 않고 실행되므로 ~/.local/bin을 인식하지 못합니다. 전체 경로를 사용하면 앱이 어떻게 실행되든 작동이 보장됩니다. spawn uvx ENOENT 오류가 표시되면 이 방법으로 해결됩니다.

구성을 저장한 후 앱을 완전히 종료(Cmd+Q)하고 다시 엽니다.

OAuth의 경우: 첫 사용 시 로그인을 위한 브라우저 창이 자동으로 열립니다. 이후에는 토큰이 캐시되어 다시 요청되지 않습니다.

옵션 B — 클론 (고급)

이 방법의 동영상 가이드를 선호하시나요? 아래 튜토리얼은 클론 설치 경로를 단계별로 다룹니다 — 가상 환경 설정, 종속성, 구성:

코드를 수정하거나 특정 로컬 버전을 실행하려는 경우 이 방법을 사용하세요. 이 방법은 자격 증명 설정 단계에 위의 동영상 튜토리얼을 사용합니다.

Python 3.11+ 필요. 이 서버는 Python 3.10 이하에서는 시작되지 않습니다 — 그리고 Claude Desktop과 같은 GUI 클라이언트에서 실행될 때는 자동으로 실패합니다 (도구가 나타나지 않고 로그 파일도 기록되지 않음). python --version으로 버전을 확인하세요. 3.11 미만이면 Python 3.11 이상을 설치하고 가상 환경을 다시 만드세요. uvx 방법(옵션 A)은 Python 버전을 자동으로 관리하여 이 문제를 완전히 피할 수 있으므로 Windows에서 권장되는 경로입니다.

저장소 클론:

git clone https://github.com/AminForou/mcp-gsc.git
cd mcp-gsc

또는 이 페이지 상단의 녹색 Code 버튼에서 ZIP을 다운로드하여 압축을 풉니다.

환경 설정:

uv venv .venv
uv pip install -r requirements.txt

AI 클라이언트 구성 (Claude Desktop 예시):

OAuth:

{
  "mcpServers": {
    "gscServer": {
      "command": "/full/path/to/mcp-gsc/.venv/bin/python",
      "args": ["/full/path/to/mcp-gsc/gsc_server.py"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
      }
    }
  }
}

서비스 계정:

{
  "mcpServers": {
    "gscServer": {
      "command": "/full/path/to/mcp-gsc/.venv/bin/python",
      "args": ["/full/path/to/mcp-gsc/gsc_server.py"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

Mac 경로 예시:

• Python: /Users/yourname/Documents/mcp-gsc/.venv/bin/python

• 스크립트: /Users/yourname/Documents/mcp-gsc/gsc_server.py

3단계 — 테스트

AI 어시스턴트에게 물어보세요: "내 GSC 속성 목록을 보여줘"

속성이 표시되면 작동하는 것입니다. 표시되지 않으면 **"get_capabilities 호출"**을 요청하여 인증 상태를 확인하고 문제를 진단하세요.

환경 변수 참조

Cursor 마켓플레이스

원클릭 설치 가능 — Cursor 마켓플레이스에서 mcp-search-console을 검색하세요.

설치 후 자격 증명을 구성하고(위 1단계 참조) Cursor Agent 채팅에서 번들된 스킬을 직접 사용하세요:

샘플 프롬프트

문제 해결

spawn uvx ENOENT 또는 command not found: uvx

AI 클라이언트가 uvx를 찾을 수 없습니다. uvx 대신 전체 경로를 사용하세요:

# Find your full path (macOS/Linux):
which uvx
# Typically: /Users/YOUR_NAME/.local/bin/uvx

# Find your full path (Windows PowerShell):
Get-Command uvx | Select-Object -ExpandProperty Source
# Typically: C:\Users\YOUR_NAME\.local\bin\uvx.exe

구성 파일에서 "command": "uvx"를 전체 경로(예: "command": "/Users/YOUR_NAME/.local/bin/uvx")로 바꾸세요.

설치 직후 uv --version에서 "command not found" 오류

설치 프로그램이 ~/.local/bin을 업데이트하지만 현재 터미널 세션에서는 아직 인식하지 못합니다. 다음을 실행하세요:

source $HOME/.local/bin/env

그런 다음 영구적으로 추가하세요:

echo 'source $HOME/.local/bin/env' >> ~/.zshrc

인증 실패 / 자격 증명 파일을 찾을 수 없음

자격 증명 파일의 절대 경로를 사용하고 있는지 확인하세요 — 상대 경로나 ~/가 아닌 절대 경로여야 합니다. 예:

/Users/yourname/Documents/client_secrets.json   ✅
~/Documents/client_secrets.json                 ✅
client_secrets.json                              ❌

MCP가 웹사이트가 아닌 Claude Desktop 앱에서만 작동함

MCP 서버는 사용자 머신에서 로컬로 실행됩니다. claude.ai/download에서 다운로드한 Claude Desktop 앱에서만 작동하며, claude.ai 브라우저 인터페이스에서는 작동하지 않습니다.

AI 클라이언트 구성 문제

1. 구성의 모든 파일 경로가 올바른 절대 경로인지 확인하세요

2. 구성 변경 후 앱을 완전히 종료(Cmd+Q)하고 다시 열어야 합니다 — 창을 닫는 것만으로는 충분하지 않습니다

3. AI 어시스턴트에게 "get_capabilities 호출"을 요청하세요 — 정확한 인증 상태와 오류를 보고합니다

안전: 파괴적 작업

기본적으로 add_site, delete_site, delete_sitemap은 비활성화되어 있습니다. 활성화하려면:

"GSC_ALLOW_DESTRUCTIVE": "true"

원격 배포 및 Docker (고급)

표준 설정은 서버를 로컬에서 실행합니다. 이 섹션은 원격 서버나 컨테이너에서 실행하려는 사용자만을 위한 것입니다.

HTTP 전송

MCP_TRANSPORT=sse MCP_HOST=0.0.0.0 MCP_PORT=3001 python gsc_server.py

Docker

docker build -t mcp-gsc .

docker run \
  -e MCP_TRANSPORT=sse \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=3001 \
  -e GSC_CREDENTIALS_PATH=/app/credentials.json \
  -v /path/to/credentials.json:/app/credentials.json \
  -p 3001:3001 \
  mcp-gsc

관련 도구

Advanced GSC Visualizer — 대화형 차트, 최대 25,000행의 원클릭 내보내기, 키워드 카니발리제이션 감지, AI 어시스턴트를 갖춘 Chrome 확장 프로그램(14,000명 이상 사용자)으로, 모두 Google Search Console 내에서 직접 사용할 수 있습니다. 동일한 작성자가 제작했습니다. Chrome 웹 스토어에서 설치 →

기여

버그를 발견했거나 개선 아이디어가 있으신가요? GitHub에서 이슈를 열거나 풀 리퀘스트를 제출해 주세요.

라이선스

MIT 라이선스. 자세한 내용은 LICENSE 파일을 참조하세요.

변경 로그

[0.3.3] — 2026년 7월

• mcp[cli]>=1.3.0,<2.0.0으로 고정. mcp SDK 2.0.0이 mcp.server.fastmcp를 제거하여 모든 새 uvx 설치가 ModuleNotFoundError로 중단되었습니다. 2.0 미만으로 제한하여 설치가 정상 작동하도록 복구했습니다. (#41 수정)

[0.3.2] — 2026년 4월

• uvx용 OAuth 브라우저 흐름 수정 — macOS에서 MCP 하위 프로세스로 실행할 때 OAuth 브라우저 창이 열리지 못하게 하던 isatty 블록을 제거했습니다. 이제 OAuth + uvx가 기본적으로 작동합니다.

• get_capabilities 도구 — 한 번의 호출로 카테고리별로 그룹화된 모든 사용 가능한 도구와 실시간 인증 상태를 반환합니다.

• 더 나은 인증 오류 메시지 — 모든 도구가 이제 자격 증명이 없거나 만료되었을 때 reauthenticate를 호출하도록 명시적으로 안내합니다.

• list_properties 설명 개선 — 지연 도구 로딩을 사용하는 클라이언트에서 더 나은 의미론적 도구 검색을 제공합니다.

[0.3.1] — 2026년 4월

• list_properties가 실제 인증 오류를 가리던 문제 수정; 자격 증명 누락 시 즉시 실패.

[0.3.0] — 2026년 4월

• 4개의 번들 SEO 스킬을 갖춘 Cursor Marketplace 플러그인

• 플랫폼 사용자 구성 디렉토리의 안정적인 토큰 저장(uvx 업그레이드 후에도 유지)

• 모든 데이터 도구에 대한 구조화된 JSON 출력

• 39개의 단위 테스트

[0.2.2] — 2026년 4월

• 파괴적 도구에 대한 안전 모드(기본적으로 비활성화)

• 원격 배포를 위한 HTTP/SSE 전송

• Dockerfile

[0.2.1] — 2026년 3월

• Google 계정 전환을 위한 reauthenticate 도구

• sitemap TypeError 충돌 수정

• 도메인 속성 404 오류 수정

[0.2.0] — 2026년 3월

• 기본적으로 dataState: "all"(GSC 대시보드와 일치)

• 유연한 row_limit 매개변수(최대 500)

• 고급 분석을 위한 다중 차원 필터링

[0.1.0] — 최초 릴리스

• 속성 관리, 검색 분석, URL 검사, sitemap 관리를 다루는 19개 도구

• OAuth 및 서비스 계정 인증