google-marketing-solutions/google_ads_mcp

Google Ads MCP Server는 Gemini와 같은 대규모 언어 모델 (LLMs)이 Google Ads API와 직접 상호 작용할 수 있도록 하는 Model Context Protocol (MCP)의 구현체입니다.

참고

이것은 공식적으로 지원되는 Google 제품이 아닙니다. 주로 실험적인 목적으로 제작되었으며 운영 환경(production)에서 사용하기 위한 것이 아닙니다. 대신 공식 Google Ads MCP Server를 사용하는 것을 고려하십시오.

Copyright Google LLC. Supported by Google LLC and/or its affiliate(s). 이 솔루션은 관련 샘플 코드 또는 데이터를 포함하여, 오직 예시 목적으로만 "있는 그대로", "사용 가능한 상태로", "모든 결함이 있는 상태로" 제공되며, 어떠한 종류의 보증이나 표현도 하지 않습니다. 이 솔루션은 실험적이고 지원되지 않으며 오직 귀하의 편의를 위해서만 제공됩니다. 귀하의 사용은 해당되는 경우 Google과의 계약을 따르며, 해당 계약에 정의된 베타 기능에 해당할 수 있습니다. 귀하가 이 솔루션의 사용과 관련하여 Google에 데이터를 제공하는 경우, 귀하는 Google이 해당 데이터를 사용하고 처리할 수 있도록 허용하는 데 필요한 모든 적절한 권리, 동의 및 권한을 보유하고 있음을 진술하고 보증합니다. 이 솔루션의 어떤 부분이라도 사용함으로써, 귀하는 귀하의 시스템에 이 솔루션의 일부를 배포하거나 귀하의 비즈니스와 관련하여 사용하는 것을 포함하여, 이 솔루션의 사용 및 Google에 의한 데이터 처리와 관련된 알려진 위험과 알려지지 않은 모든 위험을 인지하고 가정하며 수락합니다. Google에 개인 정보를 위탁하는 것과 관련하여, 귀하는 Google의 개인정보 처리방침 및 기타 공개 정보를 확인하여 구축된 시스템이 충분한지 확인해야 하며, Google이 추가적인 정보를 제공하지 않는다는 점에 동의합니다.

Google Ads MCP Server를 구성하고 실행하려면 다음 지침을 따르십시오.

이 프로젝트에는 pipx 또는 uv가 포함된 Python 3.12가 필요합니다.

이 프로젝트는 의존성 관리(dependency management)를 위해 uv를 사용합니다.

uv 설치

그 다음 다음 명령어를 실행하여 필요한 Python 패키지를 설치합니다:

uv pip sync

이 도구를 사용하려면 Google Ads API 자격 증명(credentials)이 포함된 google-ads.yaml 파일이 필요합니다. 기본적으로 애플리케이션은 홈 디렉토리에서 이 파일을 찾습니다.

파일이 없다면, google-ads-python 라이브러리의 다음 예제를 실행하여 생성할 수 있습니다:
authentication example

google-ads.yaml 파일에 다음 키(keys)가 포함되어 있는지 확인하십시오:

client_id

client_secret

refresh_token

developer_token

login_customer_id

(선택 사항이지만 권장됨)

서버는 다음 환경 변수(environment variables)를 사용하여 구성할 수 있습니다:

ADS_MCP_ENABLE_MUTATIONS
: mutation 도구를 활성화하려면 true로 설정합니다. 기본값은 false입니다.

GOOGLE_ADS_CREDENTIALS
: google-ads.yaml 파일의 경로입니다.

USE_GOOGLE_OAUTH_ACCESS_TOKEN
: Google OAuth 토큰 검증을 활성화하려면 설정합니다.

google-ads-mcp 서버를 포함하도록 Gemini 설정을 업데이트하십시오. 다음은 로컬 MCP 서버 설정의 예시입니다:

{
// 기타 설정...
mcpServers: {
...

서버가 실행되면 Gemini CLI를 사용하여 상호작용할 수 있습니다. Gemini에서 /mcp를 입력하면 결과에 Google Ads API 서버가 나열된 것을 볼 수 있습니다.

google-ads-mcp 서버를 포함하도록 Gemini 설정을 업데이트하십시오. [DIRECTORY]는 프로젝트의 절대 경로가 됩니다. 다음은 로컬 MCP 서버 설정의 예시입니다:

{
// 기타 설정...
mcpServers: {
...

서버가 실행되면 Gemini CLI를 사용하여 상호작용할 수 있습니다. Gemini에서 /mcp를 입력하면 결과에 Google Ads API 서버가 나열된 것을 볼 수 있습니다.

그 후 다음과 같은 질문을 할 수 있습니다:

• "list all campaigns"
• "show me metrics for campaign [CAMPAIGN_ID]"
• "get all ad groups"

서버를 직접 시작하려면 프로젝트 경로에서 다음 명령어를 실행하십시오:

uv run -m ads_mcp.server

서버가 시작되며 요청을 받을 준비가 됩니다.

서버는 Google Ads와 상호작용하기 위한 도구(tools)를 제공합니다. 일부 도구는 읽기 전용(read-only)이며, 다른 도구들은 변이(mutations, 수정)를 허용합니다.

GAQL 실행 (GAQL Execution): GAQL을 사용하여 Google Ads 데이터를 쿼리합니다. 계정 관리 (Account Management): 접근 가능한 계정 목록을 나열합니다. 문서 (Documentation): GAQL 및 보고 뷰(reporting views)에 대한 문서에 접근합니다.

이러한 도구들을 활성화하려면 ADS_MCP_ENABLE_MUTATIONS=true를 설정하십시오.

캠페인 예산 (Campaign Budgets): 캠페인 예산을 생성합니다. 캠페인 (Campaigns): 캠페인을 생성합니다. 광고 그룹 (Ad Groups): 광고 그룹을 생성합니다. 광고 (Ads): 광고를 생성합니다. 기준 (Criteria): 기준(예: 키워드)을 생성합니다.

기여를 환영합니다! 자세한 내용은 CONTRIBUTING.md 가이드를 참조해 주세요.

Google Ads MCP Server는 APACHE-2.0 라이선스 하에 배포되는 오픈 소스 프로젝트입니다.

질문, 제안 또는 피드백이 있다면 언제든지 이슈(issue)를 생성해 주세요.