Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Google Ads MCP 서버: 개발자 통합 가이드

모델 컨텍스트 프로토콜(MCP)은 대규모 언어 모델(LLM)이 외부 데이터 및 애플리케이션과 안전하게 상호작용할 수 있도록 하는 개방형 표준입니다. Google Ads MCP 서버는 Google Ads API에 대한 표준화된 브리지를 제공합니다. 이를 통해 AI 에이전트는 자연어를 사용하여 계정 데이터를 검색 및 분석하고, 애셋을 만들고, 동영상을 업로드하고, 라벨을 관리할 수 있습니다.

커뮤니티 리소스 및 지원

GitHub 저장소: google-ads-mcp 저장소에서 데모와 예시를 찾고, 버그를 신고하고, 기능을 제안할 수 있습니다.

버그 신고 및 기능 요청에는 Issues 탭을 사용합니다.
커뮤니티: Google 광고 커뮤니티 Discord의 #ads-api-ai-tools 채널에 참여하세요.

기술 개요

Google Ads MCP 서버를 통합하면 Google Ads API 인증, 리소스 가져오기, 데이터 파싱, 지원되는 확장 소재 또는 라벨 변형을 위한 커스텀 코드를 작성할 필요가 없습니다. 서버는 LLM이 검사하고 호출할 수 있는 호출 가능한 도구와 참조 리소스(핵심 기능 참고)를 노출합니다.

주요 사양

프로토콜: MCP(모델 컨텍스트 프로토콜)
모드: 읽기 및 부분 변형(제안 및 확인 유효성 검사 또는 구성 가능한 읽기 전용 모드를 사용한 저작물 생성, 동영상 업로드, 라벨 관리)
언어: Python 3.10 이상
전송: 표준 입력/출력(stdio) 또는 스트리밍 가능한 HTTP(Cloud Run의 streamable-http)
인증: 로컬 stdio의 애플리케이션 기본 사용자 인증 정보(OAuth 2.0 사용자 인증 정보 또는 서비스 계정) 또는 원격 HTTP의 OAuth 2.0 웹 애플리케이션 사용자 인증 정보

상호작용 루프 작동 방식

요청: "이번 주 캠페인 실적은 어때?" 또는 "여름 세일 콜아웃 확장 소재를 만들어 줘"와 같은 프롬프트를 제출합니다.
탐색: LLM은 사용 가능한 도구와 리소스를 검사하고 일치하는 google-ads-mcp 도구를 선택합니다.
실행 또는 테스트 실행 검증: 읽기 도구는 Google Ads API를 직접 쿼리합니다. 변형 도구는 먼저 제안 모드(validate_only=True)에서 실행되어 변경사항을 커밋하지 않고 입력을 검증합니다(제안 및 확인 안전 워크플로 참조).
컨텍스트 삽입: MCP 서버는 구조화된 쿼리 결과 또는 제안된 change_items 항목과 확인 checksum 다이제스트를 LLM의 컨텍스트 창에 반환합니다.
응답 및 확인: LLM이 답변을 제시하거나 제안된 변경사항을 확인하도록 요청합니다. 승인하면 LLM은 validate_only=False 및 일치하는 checksum 값으로 변형 도구를 다시 호출하여 변경사항을 커밋합니다.

시작하기

Google Ads MCP 서버를 로컬에서 구성하고 실행하려면 다음 단계를 따르세요. 대신 공유 원격 서비스를 배포하려면 Google Cloud에 배포를 참조하세요.

기본 요건

서버를 구성하기 전에 로컬 환경과 Google Cloud 콘솔에서 다음 기본 요건을 완료합니다.

Google Cloud 프로젝트: Google Ads API가 사용 설정된 Google Cloud 프로젝트를 만들거나 선택합니다. API를 사용 설정하면 테스트 계정에 대한 읽기 및 변형 워크플로를 테스트할 수 있는 테스트 액세스 권한이 부여됩니다. 프로덕션 계정에 액세스하려면 Google Ads API 개요 페이지에서 탐색기, 기본 또는 일반 액세스 권한을 확인하거나 이러한 액세스 수준 중 하나를 신청하세요. 그렇지 않으면 프로덕션 호출이 AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION 오류와 함께 실패합니다. Google은 2026년 9월 9일에 개발자 토큰(GOOGLE_ADS_DEVELOPER_TOKEN)을 지원 중단합니다. OAuth 클라이언트 또는 서비스 계정을 소유한 Google Cloud 프로젝트에 따라 API 액세스 수준이 결정됩니다.
사용자 인증 정보: 로컬 stdio 모드는 OAuth 2.0 클라이언트 보안 비밀번호 JSON 파일 또는 Cloud 프로젝트의 서비스 계정에서 애플리케이션 기본 사용자 인증 정보(ADC)를 사용하여 인증합니다. 기본 할당량 또는 ADC 프로젝트를 지정해야 하는 경우 GOOGLE_CLOUD_PROJECT 환경 변수를 설정합니다. 원격 streamable-http 배포에는 OAuth 2.0 웹 애플리케이션 클라이언트 ID 및 클라이언트 보안 비밀번호가 필요합니다(Google Cloud Run에 배포 참조).
로컬 소프트웨어(stdio 모드): Python 3.10 이상, pipx, gcloud 명령줄 도구(사용자 ADC 파일을 생성하는 데 사용)를 설치합니다.

구성

API가 사용 설정된 Google Cloud 프로젝트의 OAuth 클라이언트를 사용하여 애플리케이션 기본 사용자 인증 정보(ADC)를 생성하고 Google Ads API 범위를 포함합니다.
```
gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=PATH_TO_CLIENT_SECRET_JSON
```
다음을 바꿉니다.
- PATH_TO_CLIENT_SECRET_JSON: OAuth 2.0 클라이언트 보안 비밀번호 JSON 파일의 경로입니다.
이 명령어는 Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]를 출력합니다(예: Linux 및 macOS의 ~/.config/gcloud/application_default_credentials.json). 대신 서비스 계정으로 인증하려면 이 단계를 건너뛰고 GOOGLE_APPLICATION_CREDENTIALS가 서비스 계정 키 JSON 파일을 가리키도록 하거나 --impersonate-service-account를 gcloud auth application-default login에 전달합니다.
호스트의 MCP 구성 파일(예: ~/.gemini/config/mcp_config.json, ~/.gemini/settings.json, ~/.claude/settings.json)에 서버를 추가합니다.
```
{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "google-ads-mcp==0.0.6",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON"
      }
    }
  }
}
```
다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- PATH_TO_CREDENTIALS_JSON: 1단계에서 출력된 ADC JSON 파일 또는 서비스 계정 키 JSON 파일의 경로입니다. 기본 gcloud ADC 파일 위치를 사용하는 경우 GOOGLE_APPLICATION_CREDENTIALS를 생략할 수 있습니다.
관리자 계정을 통해 고객 계정에 액세스하려면 env에서 GOOGLE_ADS_LOGIN_CUSTOMER_ID(하이픈 없이 10자리)를 설정하거나 개별 도구 호출에서 login_customer_id 매개변수를 전달합니다.

선택사항: 에이전트에 기술 및 개발자 어시스턴트 추가

Google Ads MCP 서버는 AI 클라이언트에 계정 보고 데이터에 대한 실시간 액세스 권한과 확장 소재 생성, 동영상 업로드, 라벨 관리 도구를 제공합니다. MCP 서버를 다음 컴패니언 도구와 페어링하여 에이전트가 유효한 Google Ads Query Language(GAQL) 쿼리를 구성하고 계정 실적 변화를 진단할 수 있도록 지원합니다. 이러한 도구는 생성된 확장 소재를 캠페인에 연결하거나 지원되지 않는 다른 변형을 수행하는 스크립트와 같은 클라이언트 라이브러리 코드도 생성합니다.

Google Ads API 에이전트 기술: 에이전트가 더 낮은 토큰 오버헤드로 Google Ads MCP 서버를 사용하는 데 도움이 되는 이식 가능한 워크플로 모듈(google-ads-api-mcp-setup, google-ads-api-account-diagnostics, google-ads-api-quickstart 포함)입니다. 다음 명령어를 실행하여 설치하거나(Node.js 필요) Antigravity, Claude Code, Codex, Cursor 설정에 관한 Google Ads API 에이전트 기술 가이드를 참고하세요.
```
npx skills add google/skills/skills/ads
```
Google Ads API 개발자 어시스턴트: 로컬 Protobuf 스키마 검사, GAQL 유효성 검사, 클라이언트 라이브러리 코드 생성, 오프라인 전환 문제 해결을 제공하는 Google Antigravity 및 Claude Code용 모듈식 플러그인입니다. Google Ads API 개발자 어시스턴트란 무엇인가요?를 읽거나 설치 가이드를 따르세요.

주요 기능

다음 섹션에서는 서버의 읽기 도구, 부분 변형 도구, 참조 리소스를 설명합니다. v0.0.6부터 도구는 기본적으로 카테고리 네임스페이스 프리픽스(예: search_search)로 등록됩니다. 프리픽스가 없는 출시 버전에서 프롬프트 또는 허용 목록을 업그레이드할 때는 도구 이름을 업데이트하거나 tools_config.yaml에서 빈 프리픽스("")를 설정하세요(도구 네임스페이스 및 읽기 전용 모드 구성 참고).

읽기 도구

customers_list_accessible_customers(도구 list_accessible_customers): 인증된 사용자가 직접 액세스할 수 있는 Google Ads 고객 ID를 반환합니다.
search_search(도구 search): 원시 GAQL 문자열이 아닌 구조화된 매개변수(customer_id, resource, fields, 선택사항인 conditions, orderings, limit, login_customer_id)에서 GAQL SearchStream 쿼리를 빌드하고 실행합니다. 모든 쿼리는 PARAMETERS omit_unselected_resource_names=true를 추가하여 리소스 속성, 측정항목, 세그먼트, 예산, 상태를 깔끔하게 가져옵니다.
metadata_get_resource_metadata(도구 get_resource_metadata): Google Ads API 리소스 유형(예: "campaign")에 대해 선택, 필터링, 정렬 가능한 속성, 측정항목, 세그먼트를 가져옵니다. 이 메타데이터를 사용하여 search_search 도구를 호출하기 전에 유효한 쿼리 필드(예: v26.2와 같은 마이너 버전에 추가된 측정항목 및 세그먼트)를 검색합니다.

변형 도구(일부 지원)

assets_create_asset(도구 create_asset): TEXT, IMAGE, YOUTUBE_VIDEO, SITELINK, CALLOUT, STRUCTURED_SNIPPET 확장 소재 유형에 대한 전용 매개변수를 사용하여 독립형 Google Ads 확장 소재를 만듭니다. 다른 변경 가능한 AssetService 유형(예: PRICE, PROMOTION, CALL, BUSINESS_MESSAGE)에 extra_params 사전을 전달하고 SITELINK 애셋의 sitelink_link_text와 함께 루트 수준 final_urls를 포함합니다. 로컬 파일 경로(image_asset_path)는 로컬 stdio 모드에서만 작동합니다. 원격 HTTP 배포의 경우 image_asset_mime_type가 IMAGE_PNG, IMAGE_JPEG 또는 IMAGE_GIF로 설정된 base64로 인코딩된 image_asset_data 매개변수를 전달합니다(최대 20MB).
assets_upload_video_asset(도구 upload_video_asset): 로컬 stdio 모드에서만 Google Ads API를 통해 YouTube에 로컬 동영상 파일(.3gp, .avi, .flv, .mkv, .mov, .mp4, .mpeg, .mpg, .ogg, .webm, .wmv)을 업로드합니다. video_title 및 video_description는 모두 필수 매개변수이며 개인 정보 보호는 기본적으로 UNLISTED(또는 사용자 OAuth가 있는 광고주 소유 브랜드 채널의 경우 PUBLIC)로 설정됩니다. 이 도구는 11자(영문 기준) YouTube video_id가 아닌 Google Ads video_upload_id 값(및 리소스 이름)을 반환합니다. you_tube_video_upload.state = 'PROCESSED'까지 search_search 도구(you_tube_video_upload.video_upload_id로 필터링)를 사용하여 you_tube_video_upload를 쿼리합니다. 그런 다음 you_tube_video_upload.video_id를 youtube_video_id 매개변수로 assets_create_asset(asset_type="YOUTUBE_VIDEO")에 전달합니다.
labels_manage_labels(도구 manage_labels): 이름, 설명, 16진수 배경 색상을 포함한 계정 라벨을 만들고, 업데이트하고, 삭제합니다.
labels_manage_label_associations(도구 manage_label_associations): CAMPAIGN, CUSTOMER, AD_GROUP, AD_GROUP_CRITERION 리소스에서 CREATE 및 REMOVE 라벨 연결 작업(UPDATE는 지원되지 않음)을 지원합니다. CUSTOMER 리소스의 경우 resource_id는 선택사항이며 기본값은 customer_id입니다. AD_GROUP_CRITERION 리소스의 복합 {ad_group_id}~{criterion_id} ID를 전달하고 resource_id 및 label_id 또는 association_resource_name를 전달하여 연결을 삭제합니다. 광고 수준 AD_GROUP_AD 라벨은 지원되지 않습니다.

참조 리소스

서버는 tools_config.yaml 설정과 관계없이 마운트된 상태로 유지되는 읽기 전용 MCP 리소스 4개를 노출합니다.

resource://discovery-document: Google Ads API 리소스, 서비스 메서드, 스키마의 JSON REST 검색 개요입니다. 선택, 필터링, 정렬이 가능한 GAQL 쿼리 필드를 반환하는 metadata_get_resource_metadata 도구를 보완합니다.
resource://metrics: Google Ads API 측정항목에 대한 HTML 참고 문서입니다.
resource://segments: Google Ads API 세그먼트의 HTML 참고 문서입니다.
resource://release-notes: 버전 변경사항 및 새로운 기능을 다루는 HTML Google Ads API 출시 노트입니다.

제안 및 확인 안전 워크플로

모든 변경 도구(assets_create_asset, assets_upload_video_asset, labels_manage_labels, labels_manage_label_associations)는 의도하지 않은 계정 수정을 방지하기 위해 2단계 제안 및 확인 워크플로를 시행합니다.

제안(validate_only=True, 기본값): 변경사항을 커밋하지 않고 입력을 검증합니다. 애셋 및 라벨 도구는 실시간 Google Ads API validate_only 드라이 런을 실행합니다. YouTubeVideoUploadService에는 테스트 실행 모드가 없으므로 assets_upload_video_asset는 로컬 파일을 검증하고 크기와 수정 타임스탬프를 바인딩합니다. 각 도구는 사람이 읽을 수 있는 change_items 항목과 customer_id 매개변수 및 요청 페이로드에 바인딩된 스테이트리스(Stateless) SHA-256 checksum 다이제스트를 반환합니다.
확인(validate_only=False): change_items 목록을 표시하고 승인을 받은 후 에이전트는 validate_only=False, 동일한 customer_id 매개변수 및 인수, 1단계의 checksum 값을 사용하여 도구를 다시 호출합니다. 서버는 계정을 변경하기 전에 누락되거나 일치하지 않는 체크섬을 거부합니다.

도구 네임스페이스 및 읽기 전용 모드 구성

서버는 5가지 도구 카테고리(customers, search, metadata, labels, assets)가 모두 사용 설정된 기본 tools_config.yaml 파일을 번들로 묶습니다. tools_config.yaml를 맞춤설정하여 개별 도구 또는 네임스페이스를 선택적으로 사용 설정 또는 중지하거나, 네임스페이스 프리픽스를 변경 또는 삭제하거나, 엄격한 읽기 전용 배포를 적용합니다.

시작 시 서버는 다음 순서로 tools_config.yaml를 확인합니다.

GOOGLE_ADS_MCP_TOOLS_CONFIG 환경 변수의 명시적 경로(작업 디렉터리가 프로젝트 폴더와 다를 수 있는 로컬 stdio 호스트에 권장됨)
서버의 현재 작업 디렉터리에 있는 tools_config.yaml 파일
패키지와 번들로 제공되는 기본 tools_config.yaml 파일입니다.

GOOGLE_ADS_MCP_TOOLS_CONFIG가 누락된 파일을 가리키거나 확인된 구성 파일이 잘못된 경우 서버는 기본값으로 대체하는 대신 시작 시 오류를 발생시킵니다.

다음 최소 tools_config.yaml 파일은 엄격한 읽기 전용 배포를 적용합니다.

namespaces:
  customers: true
  search: true
  metadata: true
  labels: false
  assets: false

다음 tools_config.yaml 파일은 프리픽스를 맞춤설정하고 개별 도구를 필터링합니다(예: Cloud Run에서 base64 create_asset 도구를 노출하고 로컬 전용 upload_video_asset 도구는 사용 중지).

namespaces:
  # Default prefix ("customers_list_accessible_customers")
  customers: true

  # Empty prefix mounts unprefixed tool names ("search")
  search: ""

  # Custom prefix ("schema_get_resource_metadata")
  metadata: "schema"

  # Enable only specific tools in a multi-tool category
  assets:
    enabled_tools:
      - create_asset

시작을 위한 샘플 프롬프트

서버를 연결한 후 MCP 클라이언트에서 다음 프롬프트를 사용해 보세요.

서버가 할 수 있는 작업 물어보기

What can the google-ads-mcp server do?

고객에 대해 질문하기

What customers do I have access to?

캠페인에 대해 질문하기

How many active campaigns do I have?

How is my campaign performance this week?

Give me a report of the top spending campaigns split by device category over the last 7 days for account 1234567890

저작물 만들기, 동영상 업로드, 라벨 관리

Create a callout asset with the text "Free Shipping" for account 1234567890

Upload /path/to/promo.mp4 with title "Summer Sale" and description "Summer promo video" for account 1234567890

Create a label named "Q4 Promo" with background color #34A853 and apply it to campaign 9876543210 in account 1234567890

Google Cloud에 배포

여러 에이전트에서 MCP 서버를 공유하거나 웹 서비스로 실행하려면 로컬에서 실행하는 대신 Google Cloud Run 또는 다른 클라우드 인프라 제공업체에서 호스팅하세요.

기본 요건

Google Ads API가 사용 설정된 Google Cloud 프로젝트(프로덕션 액세스 요구사항은 기본 요건 참고)
gcloud 명령줄 도구가 설치, 인증되고 활성 프로젝트로 구성되어 있습니다.
```
gcloud config set project PROJECT_ID
```
다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.

Docker 이미지 빌드 및 푸시

Cloud Build를 사용하여 로컬에 Docker를 설치하지 않고 컨테이너 이미지를 빌드하고 Artifact Registry에 푸시합니다.

Artifact Registry에서 저장소를 만듭니다.

gcloud artifacts repositories create mcp-servers \
  --repository-format=docker --location=us-central1

GitHub 저장소의 출시 태그(또는 Dockerfile 또는 tools_config.yaml를 맞춤설정한 경우 로컬 체크아웃의 .)에서 이미지를 빌드하고 제출합니다.
```
gcloud builds submit https://github.com/googleads/google-ads-mcp \
  --git-source-revision=v0.0.6 \
  --tag=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6
```
다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
google-ads-mcp를 업데이트하거나 새 Google Ads API 출시 버전(예: v26.2)에 맞게 번들로 제공되는 google-ads Python 클라이언트 라이브러리를 업그레이드할 때마다 이미지를 다시 빌드하고 다시 배포합니다.

Google Cloud Run에 배포

Cloud Run 서비스에 다음 환경 변수와 보안 비밀을 구성합니다.

GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: 애플리케이션 수준 OAuth 인증을 위한 API 지원 Google Cloud 프로젝트의 OAuth 2.0 웹 애플리케이션 클라이언트 ID입니다. 다음 OAuth 구성 단계를 완료합니다.
- 연결하려는 AI 클라이언트(예: https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect, https://antigravity.google/oauth-callback)에 승인된 리디렉션 URI를 추가합니다.
- API 및 서비스 > OAuth 동의 화면 > 데이터 액세스(범위 추가 또는 삭제)에서 OAuth 동의 화면에 https://www.googleapis.com/auth/adwords 범위를 추가합니다.
- OAuth 동의 화면 게시 상태가 테스트(기본값)로 설정된 경우 MCP 서버에 연결하는 Google 계정을 API 및 서비스 > OAuth 동의 화면 > 대상(테스트 사용자 > + 사용자 추가)에서 테스트 사용자로 추가합니다.
GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: OAuth 클라이언트 ID에 해당하는 OAuth 클라이언트 보안 비밀번호입니다.
GOOGLE_ADS_MCP_BASE_URL: MCP 서버의 공개 기준 URL입니다(예: https://google-ads-mcp-xyz-uc.a.run.app). Cloud Run은 초기 배포 중에 이 URL을 할당하므로 먼저 이 변수 없이 배포하고 나중에 서비스를 업데이트합니다.
GOOGLE_ADS_MCP_JWT_SIGNING_KEY(멀티 인스턴스 Cloud Run에 권장): 컨테이너 다시 시작 및 수평 확장에서 FastMCP JWT에 서명하는 영구 보안 비밀입니다.
GOOGLE_ADS_MCP_STORAGE_TYPE(멀티 인스턴스 Cloud Run에 권장): OAuth 클라이언트 등록 및 토큰의 영구 백엔드(GOOGLE_ADS_MCP_STORAGE_REDIS_URL가 있는 redis 또는 firestore). 기본 v0.0.6 Dockerfile는 인메모리 백엔드만 설치하므로 먼저 커스텀 Dockerfile에 py-key-value-aio[redis] 또는 .[firestore]를 설치합니다. firestore를 사용하려면 Firestore 데이터베이스와 Cloud Run 서비스 계정에 대한 roles/datastore.user IAM 역할도 필요합니다. 인메모리 스토리지를 사용한 단일 인스턴스 테스트의 경우 --max-instances=1를 전달합니다.
GOOGLE_ADS_LOGIN_CUSTOMER_ID(선택사항): 도구 호출에서 login_customer_id 매개변수를 생략할 때 사용되는 기본 10자리 관리자 고객 ID(하이픈 제외)입니다.
GOOGLE_ADS_MCP_TOOLS_CONFIG(선택사항): 커스텀 tools_config.yaml 파일의 컨테이너 경로입니다(예: 이미지를 다시 빌드하지 않고 읽기 전용 모드를 적용하기 위해 /etc/mcp/tools_config.yaml의 Secret Manager에서 마운트됨). 도구 네임스페이스 및 읽기 전용 모드 구성을 참조하세요.

Secret Manager에 GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET 및 GOOGLE_ADS_MCP_JWT_SIGNING_KEY를 저장하고 서비스를 Google Cloud Run에 배포합니다.

gcloud run deploy google-ads-mcp \
  --image=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6 \
  --platform=managed \
  --region=us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=CLIENT_ID" \
  --set-secrets="GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=MCP_OAUTH_CLIENT_SECRET:latest,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=MCP_JWT_SIGNING_KEY:latest"

Cloud Run에서 배포를 완료한 후 할당된 서비스 URL을 검색하고 GOOGLE_ADS_MCP_BASE_URL 환경 변수로 서비스를 업데이트합니다.

gcloud run services update google-ads-mcp \
  --region=us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://CLOUD_RUN_SERVICE_URL"

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
CLIENT_ID: OAuth 2.0 웹 애플리케이션 클라이언트 ID입니다.
MCP_OAUTH_CLIENT_SECRET: OAuth 2.0 클라이언트 보안 비밀번호를 저장하는 Secret Manager 보안 비밀 이름입니다.
MCP_JWT_SIGNING_KEY: JWT 서명 키를 저장하는 Secret Manager 보안 비밀 이름입니다.
CLOUD_RUN_SERVICE_URL: Cloud Run 서비스에 할당된 호스트 이름입니다(예: google-ads-mcp-xyz-uc.a.run.app).

인증 및 보안 모델

--allow-unauthenticated로 배포하면 Cloud Run의 인프라 IAM 검사(roles/run.invoker)가 사용 중지되므로 외부 AI 클라이언트가 Google Cloud 서비스 계정 토큰 없이 연결할 수 있습니다. 인증은 애플리케이션 계층에 위임됩니다.

GOOGLE_ADS_MCP_OAUTH_CLIENT_ID 및 GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET가 설정되면 서버는 모든 요청에 Google OAuth 2.0을 적용하고 인증되지 않은 호출자에게 401 Unauthorized HTTP 상태 코드를 반환합니다. 모든 도구 호출은 인증된 호출자의 OAuth ID로 실행됩니다.
--allow-unauthenticated를 생략하면 호출자가 모든 요청에 Google Cloud OIDC ID 토큰을 전달해야 합니다. 표준 AI 클라이언트(예: Claude 및 ChatGPT)는 Google Cloud IAM 토큰이 아닌 최종 사용자 OAuth를 사용하므로 직접 연결하려면 애플리케이션 수준 OAuth와 페어링된 --allow-unauthenticated가 필요합니다.

MCP 클라이언트 구성

배포 후 Cloud Run 서비스 URL로 MCP 클라이언트를 구성합니다. 서버가 OAuth 2.0을 적용하므로 클라이언트는 MCP OAuth 흐름을 지원하거나 승인된 Bearer 토큰을 제공해야 합니다.

OAuth 지원 클라이언트: MCP OAuth 검색을 지원하는 클라이언트(예: Antigravity)에서 연결하면 Google 로그인 메시지가 트리거되어 https://www.googleapis.com/auth/adwords 범위(Google Cloud 콘솔에 .../auth/adwords로 표시됨)를 부여합니다.
서드 파티 AI 플랫폼(Claude, ChatGPT): 클라이언트의 커넥터 설정에서 /mcp 경로(예: https://google-ads-mcp-xyz-uc.a.run.app/mcp)를 사용하여 서비스 URL을 가리키는 커스텀 커넥터를 추가합니다. OAuth 클라이언트 ID 및 클라이언트 보안 비밀번호를 사용하여 OAuth 2.0 인증을 선택하고 클라이언트의 콜백 URI가 OAuth 클라이언트의 승인된 리디렉션 URI에 있는지 확인합니다.
OAuth 지원이 없는 클라이언트: HTTP OAuth 흐름을 지원하지 않는 클라이언트는 401 Unauthorized HTTP 상태 코드를 수신합니다. 이러한 클라이언트의 경우 대신 로컬 stdio 구성을 사용합니다.

다음 예시에서는 ~/.gemini/settings.json에서 gemini 명령줄 도구를 구성합니다(~/.gemini/config/mcp_config.json의 Google Antigravity의 경우 "httpUrl"를 "serverUrl" 또는 "url"로 바꿈).

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://CLOUD_RUN_SERVICE_URL/mcp"
    }
  }
}

다음을 바꿉니다.

CLOUD_RUN_SERVICE_URL: Cloud Run 서비스에 할당된 호스트 이름입니다(예: google-ads-mcp-xyz-uc.a.run.app).

Google Ads MCP 서버: 개발자 통합 가이드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

커뮤니티 리소스 및 지원

기술 개요

주요 사양

상호작용 루프 작동 방식

시작하기

기본 요건

구성

선택사항: 에이전트에 기술 및 개발자 어시스턴트 추가

주요 기능

읽기 도구

변형 도구(일부 지원)

참조 리소스

제안 및 확인 안전 워크플로

도구 네임스페이스 및 읽기 전용 모드 구성

시작을 위한 샘플 프롬프트

서버가 할 수 있는 작업 물어보기

고객에 대해 질문하기

캠페인에 대해 질문하기

저작물 만들기, 동영상 업로드, 라벨 관리

Google Cloud에 배포

기본 요건

Docker 이미지 빌드 및 푸시

Google Cloud Run에 배포

인증 및 보안 모델

MCP 클라이언트 구성

다음 단계

Google Ads MCP 서버: 개발자 통합 가이드