Google Ads MCP 서버로 광고 리포트 받기 — 읽기 전용으로 안전하게 연결하는 6단계

KAITABASE가 공식 문서와 원문을 직접 읽고 새로 쓴 가이드입니다.

이 가이드로 할 수 있는 것

Google Ads MCP 서버는 AI 에이전트가 자연어로 Google Ads 캠페인 데이터를 가져오게 해 주는 MCP(Model Context Protocol) 서버입니다. 공식 문서는 이 서버가 인증 · 리소스 조회 · 결과 해석을 위한 연결 코드를 따로 짜지 않아도 되게 해 준다고 설명합니다.

가장 중요한 성격은 읽기 전용입니다. 공식 문서는 "현재 릴리스는 읽기 전용이며, 입찰가를 바꾸거나 캠페인을 일시중지하거나 새 애셋을 만들 수 없다"고 밝힙니다. 그래서 AI가 실수로 광고 설정을 바꿀 걱정 없이, 성과 조회 · 리포트 정리만 맡기기에 알맞습니다.

끝까지 따라 하면 다음이 됩니다.

1. 서버를 가상환경에 설치해 도구 목록을 직접 확인합니다.
2. Google Cloud 프로젝트 · 인증(ADC)을 준비합니다.
3. Claude Code에 서버를 등록하고 캠페인 성과를 물어봅니다.

빠른 시작

공식 문서가 안내하는 기본 연결 방식은 MCP 설정 파일에 아래 항목을 넣는 것입니다. AI 도구가 pipx 로 서버를 내려받아 STDIO로 실행합니다.

1234567891011121314151617{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

연결되면 이렇게 물어봅니다(README 예시 프롬프트).

How is my campaign performance this week?

STEP 1. 서버가 무엇을 할 수 있는지 먼저 확인하기

목표: 연결하기 전에 도구 이름과 "읽기 전용"을 내 눈으로 확인합니다. · 예상 시간: 10분

인증 없이도 서버를 띄워 도구 목록은 볼 수 있습니다. 2026-10-22에 직접 실행한 순서입니다.

123456mkdir gads-mcp
cd gads-mcp
git clone --depth 1 https://github.com/googleads/google-ads-mcp.git repo
python -m venv .venv
.\.venv\Scripts\python -m pip install .\repo
.\.venv\Scripts\python -m pip show google-ads-mcp

확인 Version: 0.0.5 가 나옵니다(2026-10-22 기준 저장소 · PyPI 최신). 함께 설치된 의존성은 google-ads 34.0.0, fastmcp 4.1.3, mcp 2.3.0이었습니다.

MCP 클라이언트로 STDIO 서버에 접속해 도구 목록을 요청하자, 다음이 돌아왔습니다. 인증 정보 없이 GOOGLE_PROJECT_ID 에 임의 값만 넣었고, 실제 API 호출은 하지 않았습니다.

12345server: Google Ads Server 4.1.3
tool: customers_list_accessible_customers | readOnlyHint= True
tool: metadata_get_resource_metadata | readOnlyHint= True
tool: search_search | readOnlyHint= True
resources: ['resource://discovery-document', 'resource://metrics', 'resource://release-notes', 'resource://segments']

주의 공식 문서와 README 첫머리는 도구 이름을 search, list_accessible_customers, get_resource_metadata 로 적지만, 이번에 설치한 0.0.5는 기본 설정(tools_config.yaml)에서 이름 앞에 분류(namespace)를 붙였습니다. README 아래쪽 배포 절에도 같은 이름이 나옵니다. AI에게 도구 이름을 직접 지시할 때는 실제 이름을 씁니다.

확인 search_search 의 코드는 SELECT ... FROM ... 문을 만들어 GoogleAdsService.search_stream 으로 조회만 합니다. 바꾸는(mutate) 호출은 없습니다.

되돌리기 gads-mcp 폴더를 지우면 설치한 것이 모두 사라집니다.

STEP 2. Google Cloud 프로젝트와 API 접근 준비하기

목표: 서버가 내 광고 계정을 읽을 수 있는 프로젝트를 준비합니다. · 예상 시간: 10분

공식 문서 기준(직접 실행 안 함):

1. Google Cloud 프로젝트 ID를 확인합니다. 이 값이 GOOGLE_PROJECT_ID 입니다.
2. 그 프로젝트에서 Google Ads API를 사용 설정합니다.
3. Google Ads API 개요 페이지에서 프로젝트가 Explorer · Basic · Standard 접근 수준 중 하나를 가졌는지 보고, 없으면 신청합니다.

주의 공식 문서(2026-10-16 갱신)는 개발자 토큰(GOOGLE_ADS_DEVELOPER_TOKEN)이 2026년 9월 9일에 종료되었고, 접근 수준이 Google Cloud 프로젝트에 묶이므로 최신 서버에서는 더 이상 필요 없다고 적습니다. 반면 README의 설정 예시에는 아직 GOOGLE_ADS_DEVELOPER_TOKEN 줄이 남아 있고 "선택(Optional)"으로 표시돼 있습니다. 새로 연결한다면 공식 문서를 따라 토큰 없이 시작합니다.

막히면 "The developer token is only approved for use with test accounts" 오류가 나면 실계정 접근 수준이 아직 없는 것입니다. README는 접근 수준 문서를 보고 필요한 수준을 신청하라고 안내합니다.

STEP 3. 인증 만들기(ADC)

목표: 광고 계정 권한이 있는 내 Google 계정으로 서버가 로그인하게 합니다. · 예상 시간: 10분

공식 문서 기준(직접 실행 안 함): README는 사용자 인증 정보로 ADC(Application Default Credentials)를 만드는 명령을 안내합니다. OAuth 클라이언트 JSON을 먼저 내려받아 YOUR_CLIENT_JSON_FILE 자리에 넣습니다.

gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=YOUR_CLIENT_JSON_FILE

인증에는 Google Ads API 범위 https://www.googleapis.com/auth/adwords 가 꼭 들어가야 합니다.

확인 명령이 끝나면 Credentials saved to file: [PATH_TO_CREDENTIALS_JSON] 줄이 나옵니다. 이 경로가 GOOGLE_APPLICATION_CREDENTIALS 값입니다.

막히면 관리자(MCC) 계정을 거쳐 고객 계정에 접근한다면 GOOGLE_ADS_LOGIN_CUSTOMER_ID 에 관리자 계정의 고객 ID를 넣습니다. README에 따르면 도구 호출마다 login_customer_id 를 넘길 수도 있고, 이 값이 환경 변수보다 우선합니다.

STEP 4. Claude Code에 등록하기

목표: Claude Code가 대화 중에 광고 데이터를 조회하게 합니다. · 예상 시간: 5분

공식 문서 기준(직접 실행 안 함): Claude Code 공식 MCP 문서의 STDIO 서버 추가 형식으로 등록합니다. --env 와 서버 이름 사이에는 --transport stdio 같은 다른 옵션을 하나 두어야 합니다(이름을 환경 변수 쌍으로 잘못 읽기 때문입니다).

claude mcp add --env GOOGLE_PROJECT_ID=YOUR_PROJECT_ID --env GOOGLE_APPLICATION_CREDENTIALS=C:\path\to\credentials.json --transport stdio --scope local google-ads -- pipx run --spec git+https://github.com/googleads/google-ads-mcp.git google-ads-mcp
claude mcp get google-ads

--scope local(기본값)은 내 컴퓨터의 이 프로젝트에서만 보입니다. 인증 파일 경로가 들어가므로 팀과 공유되는 --scope project(.mcp.json)는 피하는 편이 안전합니다.

주의 README는 Claude Code 설정 위치를 ~/.claude/settings.json 으로 적지만, Claude Code 공식 MCP 문서는 MCP 서버를 ~/.claude.json(local · user 범위) 또는 프로젝트 루트의 .mcp.json(project 범위)에 저장한다고 설명합니다. 파일을 손으로 고치지 말고 위의 claude mcp add 명령을 쓰면 위치를 헷갈릴 일이 없습니다.

되돌리기 claude mcp remove google-ads --scope local

STEP 5. 첫 질문 · 리포트 받기

목표: 계정 목록 → 캠페인 성과 순으로 실제 데이터를 확인합니다. · 예상 시간: 3분

공식 문서 기준(직접 실행 안 함). README가 권하는 첫 질문 순서입니다.

what customers do I have access to?
How many active campaigns do I have for customer id 1234567890
How is my campaign performance this week?

README는 대부분의 질문에서 에이전트가 고객 ID를 물어보므로, 여러 계정을 오갈 때는 질문에 고객 ID를 넣는 편이 간단하다고 안내합니다. 고객 ID는 123-456-7890 이 아니라 1234567890 처럼 하이픈 없이 씁니다(search 도구 설명).

확인 답에 실제 캠페인 이름과 숫자가 나오면 연결된 것입니다. 숫자는 Google Ads 화면의 같은 기간 값과 한 번 대조합니다.

막히면 날짜 조건은 YYYY-MM-DD 형식이고 시작일과 종료일이 모두 있어야 합니다. change_event 리소스는 LIMIT을 10000 이하로 지정해야 합니다(도구 설명의 힌트).

STEP 6. 여러 사람이 쓸 때는 Cloud Run 원격 배포 검토하기

목표: 팀 공용으로 쓸 때의 구조와 위험을 압니다. · 예상 시간: 2분

공식 문서 기준(직접 실행 안 함): 서버를 Cloud Run에 올리면 Streamable HTTP로 여러 에이전트가 같이 쓸 수 있습니다. 이때는 OAuth Client ID · Secret(GOOGLE_ADS_MCP_OAUTH_CLIENT_ID, GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET)을 이용한 OAuth 프록시 방식만 지원합니다. Claude · ChatGPT 같은 서비스는 /mcp 주소를 사용자 지정 커넥터로 붙이고, OAuth를 지원하지 않는 클라이언트는 401을 받으므로 STDIO를 써야 합니다.

주의 공식 문서는 OAuth Client ID · Secret 없이 --allow-unauthenticated 로 배포하지 말라고 경고합니다. 그러면 서버가 ADC로 돌아가 컨테이너의 서비스 계정을 아무나 쓰게 됩니다. OAuth 동의 화면에는 https://www.googleapis.com/auth/adwords 범위를 넣고, 테스트 상태라면 연결할 계정을 테스트 사용자로 추가합니다.

잘못 쓰는 예 · 바르게 쓰는 예

바로 쓰는 프롬프트 · 템플릿

주간 리포트를 받을 때:

12345google-ads MCP 서버로 고객 ID 1234567890 의 지난주(월~일) 캠페인별 성과를 조회해 주세요.
필드: 캠페인 이름, 상태, 노출수, 클릭수, 비용, 전환수.
1) 비용이 큰 순서로 표를 만들고
2) 전주 대비 비용이 30% 이상 변한 캠페인만 따로 짚어 주세요.
3) 실행한 GAQL 문을 맨 아래에 그대로 적어 주세요. 설정 변경 제안은 하지 마세요.

조회할 필드를 모를 때:

metadata_get_resource_metadata 로 campaign 리소스에서 쓸 수 있는 지표 필드를 보여 주고,
그중 전환 관련 필드만 골라 이름과 뜻을 표로 정리해 주세요.

주의할 점

• 요금: 서버 자체는 오픈소스라 무료입니다. Cloud Run · Cloud Build 등 Google Cloud 자원을 쓰면 그 요금이 붙고, AI 도구의 토큰 사용량도 따로 듭니다. 가격은 Google Cloud 가격 페이지에서 확인합니다.
• 권한: 서버는 인증한 사용자가 볼 수 있는 모든 계정을 읽습니다. 꼭 필요한 계정에만 권한이 있는 사용자로 ADC를 만듭니다.
• 보안 · 자료 반출: README는 "MCP 서버가 연결한 에이전트나 LLM에 내 데이터를 노출한다"고 적습니다. 광고 성과 데이터가 AI 서비스로 넘어가므로 회사 규정을 먼저 확인합니다. README에 따르면 사용 통계 수집을 위해 API 호출에 헤더가 하나 추가됩니다.
• 변경 작업: 입찰 · 일시중지 같은 변경은 이 서버로 할 수 없습니다. 공식 문서는 변경용 코드 생성에는 Google Ads API Developer Assistant를 안내합니다.
• 라이선스: 서버 코드는 Apache-2.0, 문서는 CC BY 4.0, 문서의 코드 예시는 Apache 2.0입니다.

공식 자료

• Google Ads MCP server 공식 문서 — https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server
• googleads/google-ads-mcp 저장소 — https://github.com/googleads/google-ads-mcp
• PyPI google-ads-mcp — https://pypi.org/project/google-ads-mcp/
• GAQL 문법 — https://developers.google.com/google-ads/api/docs/query/grammar
• Claude Code MCP 연결 문서 — https://code.claude.com/docs/en/mcp

더 보기

이 가이드는 KAITABASE가 공식 문서와 원문을 직접 읽고 실행해 본 뒤 새로 쓴 자료입니다. 같은 주제의 다른 글은 KAITABASE에서 이어서 볼 수 있습니다.

• 도구 연결 자료 모음 — https://kaitabase.vercel.app/?area=connect
• KAITABASE 전체 자료 — https://kaitabase.vercel.app