Google Ads MCP 서버

이 저장소는 Google Ads API와 상호작용하는 MCP 서버를 실행하기 위한 소스 코드를 포함합니다.

도구

서버는 Google Ads API를 사용하여 LLM 및 AI 에이전트와 함께 사용할 수 있는 여러 도구 및 리소스를 제공합니다.

사용 가능한 도구

• search: Google Ads 계정에 대한 정보를 검색합니다.

• get_resource_metadata: "campaign"과 같은 Google Ads API 리소스 유형에 대한 메타데이터를 검색합니다. 이는 데이터 구조와 쿼리 가능한 필드를 이해하는 데 유용합니다.

• list_accessible_customers: 호출을 인증하는 사용자가 직접 액세스할 수 있는 고객의 ID를 반환합니다.

도구 구성 및 네임스페이싱

Google Ads MCP 서버는 tools_config.yaml을 사용하여 개별 도구 또는 도구 카테고리(네임스페이스)를 선택적으로 활성화/비활성화하고 네임스페이스 접두사를 사용자 지정할 수 있습니다.

모든 도구가 활성화된 기본 tools_config.yaml이 패키지에 번들로 제공되므로 추가 설정 없이 서버를 즉시 사용할 수 있습니다. 설치를 사용자 지정하려면 서버가 다음 순서로 구성을 확인합니다.

1. GOOGLE_ADS_MCP_TOOLS_CONFIG 환경 변수를 통해 설정된 명시적 경로.

2. 현재 작업 디렉토리의 tools_config.yaml 파일.

3. 패키지에 번들로 제공된 기본 tools_config.yaml.

명시적으로 요청된 구성 파일(환경 변수를 통해)이 없거나 확인된 파일이 유효하지 않은 경우 서버는 오류를 발생시키고 시작에 실패합니다.

구성 예시:

namespaces:
  # Option 1: Enable category 'customers' with default prefix -> "customers_list_accessible_customers"
  customers: true

  # Option 2: Enable category 'search' with a custom prefix -> "query_search"
  search: "query"

  # Option 3: Fine-grained control over tools in a category
  metadata:
    enabled: true
    prefix: "metadata"
    enabled_tools:
      - get_resource_metadata: true

사용 가능한 리소스

• discovery-document: Google Ads API 검색 문서를 검색합니다. Google Ads API의 최신 버전에 대한 검색 문서를 제공하며, 리소스, 메서드 및 스키마를 포함한 API 표면을 설명합니다. 호스트 LLM은 이 리소스에 액세스하여 Google Ads API의 구조를 이해하고 사용 가능한 기능을 발견해야 합니다.

• metrics: Google Ads API에서 보고에 사용할 수 있는 측정항목에 대한 정보를 검색합니다.

• segments: Google Ads API에서 보고에 사용할 수 있는 세그먼트에 대한 정보를 검색합니다.

• release-notes: Google Ads API 최신 버전의 릴리스 노트를 검색합니다.

Related MCP server: gads

참고 사항

1. MCP 서버는 연결된 에이전트 또는 LLM에 데이터를 노출합니다.

2. 기술적인 문제가 있는 경우 GitHub 이슈 트래커를 사용해 주세요.

3. 사용 데이터 수집을 지원하기 위해 API 호출에 추가 헤더가 포함되어 있습니다. 이 데이터는 제품 개선에 사용됩니다.

설정 지침

설정에는 다음 단계가 포함됩니다.

1. Python 구성.

2. 개발자 토큰 구성.

3. 프로젝트에서 API 활성화.

4. 자격 증명 구성.

5. MCP 클라이언트 구성.

Python 구성

pipx 설치.

개발자 토큰 구성

개발자 토큰 얻기 지침을 따르세요.

개발자 토큰은 프로덕션 계정을 쿼리하려면 최소한 탐색기 액세스 권한이 있어야 합니다. 새 토큰은 자동으로 탐색기 액세스로 업그레이드될 수 있습니다. 그렇지 않은 경우 API 센터를 통해 신청할 수 있습니다. 자세한 내용은 액세스 수준 문서를 참조하세요.

"개발자 토큰이 테스트 계정에서만 사용하도록 승인되었습니다" 오류가 표시되면 토큰에 아직 프로덕션 계정에 대한 액세스 권한이 없는 것입니다. 필요한 액세스 수준을 요청하는 방법은 액세스 수준 문서를 참조하세요.

프로젝트에서 API 활성화

Google Cloud 프로젝트에서 다음 API를 활성화하려면 지침을 따르세요.

• Google Ads API

자격 증명 구성

옵션 1: FastMCP OAuth 프록시 사용

서버는 동적 사용자 인증을 위해 FastMCP의 OAuth 프록시 기능을 지원합니다. 이는 서버를 웹 서비스로 실행할 때 유용합니다.

활성화하려면 다음 환경 변수를 설정하세요.

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Google Cloud OAuth 2.0 클라이언트 ID.

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Google Cloud OAuth 2.0 클라이언트 시크릿.

• GOOGLE_ADS_MCP_BASE_URL: (선택 사항) 서버에 액세스할 수 있는 기본 URL(기본값: http://localhost:8080).

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: (선택 사항) 여러 서버 인스턴스 또는 배포에서 FastMCP JWT 토큰을 서명하는 데 사용되는 비밀 키.

• GOOGLE_ADS_MCP_STORAGE_TYPE: (선택 사항) OAuth 상태를 위한 스토리지 백엔드(filetree, redis, firestore 또는 memory).

• GOOGLE_ADS_MCP_STORAGE_PATH: (선택 사항) filetree 영구 스토리지의 디렉토리 경로.

• GOOGLE_ADS_MCP_STORAGE_REDIS_URL: (선택 사항) redis 영구 스토리지의 Redis URL.

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_PROJECT: (선택 사항) firestore 영구 스토리지의 Google Cloud 프로젝트. 기본값은 애플리케이션 기본 자격 증명에서 유추된 프로젝트입니다. 설정하면 GOOGLE_ADS_MCP_STORAGE_TYPE이 설정되지 않은 경우에도 firestore 백엔드가 선택됩니다.

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_DATABASE: (선택 사항) firestore 영구 스토리지의 Firestore 데이터베이스 이름. 기본값은 (default)입니다.

• GOOGLE_ADS_MCP_STORAGE_ENCRYPTION_KEY: (선택 사항) 저장된 OAuth 토큰의 암호화 키.

• GOOGLE_ADS_MCP_STORAGE_DISABLE_ENCRYPTION: (선택 사항) 토큰 암호화를 비활성화하려면 true로 설정합니다.

redis 및 firestore 백엔드는 서버와 함께 해당 스토리지 라이브러리를 설치해야 합니다: 각각 pip install py-key-value-aio[redis] 및 pip install google-ads-mcp[firestore].

활성화되면 MCP 클라이언트를 통해 API에 인증할 수 있습니다.

이러한 변수가 설정되면 서버는 자동으로 stdio 대신 streamable-http 전송(SSE/HTTP)으로 전환합니다.

서버를 별도의 프로세스로 실행하고 MCP 클라이언트가 SSE 엔드포인트(예: http://localhost:8080/mcp)에 연결하도록 구성해야 합니다.

옵션 2: 애플리케이션 기본 자격 증명을 사용하여 자격 증명 구성

애플리케이션 기본 자격 증명(ADC)을 구성하세요. 자격 증명이 Google Ads 계정 또는 속성에 액세스할 수 있는 사용자용인지 확인하세요.

자격 증명에는 Google Ads API 범위가 포함되어야 합니다:

https://www.googleapis.com/auth/adwords

OAuth 클라이언트를 만드는 방법은 OAuth 클라이언트 관리를 확인하세요.

다음은 유용할 수 있는 몇 가지 샘플 gcloud 명령입니다:

• OAuth 데스크톱 또는 웹 클라이언트와 사용자 자격 증명을 사용하여 ADC 설정(클라이언트 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

• 서비스 계정 가장을 사용하여 ADC 설정.

  gcloud auth application-default login \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
    --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform

gcloud auth application-default 명령이 완료되면 다음 메시지에 콘솔에 출력된 PATH_TO_CREDENTIALS_JSON 파일 위치를 복사하세요. 이후 단계에서 필요합니다!

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

옵션 3: Google Ads API Python 클라이언트 라이브러리를 사용하여 자격 증명 구성.

지침에 따라 Google Ads API Python 클라이언트 라이브러리를 설정하고 구성하세요.

이미 이 작업을 수행했으며 작동하는 google-ads.yaml이 있는 경우 이 파일을 재사용할 수 있습니다!

utils.py 파일에서 get_googleads_client()가 load_from_storage() 메서드를 사용하도록 변경하세요.

MCP 클라이언트 구성

서버를 MCP 클라이언트 구성에 추가하세요. 다음은 인기 있는 클라이언트의 예입니다.

Antigravity CLI / Antigravity Code Assist

1. Antigravity CLI 또는 Antigravity Code Assist를 설치하세요.

2. 서버를 구성하세요. MCP 서버 설정에 대한 자세한 내용은 https://antigravity.google/docs/mcp의 문서를 참조하세요.

• 옵션 1: FastMCP OAuth 프록시 사용(Streamable HTTP)

  서버를 별도의 프로세스로 실행하고 MCP 클라이언트가 SSE 엔드포인트(예: http://localhost:8080/mcp)에 연결하도록 구성할 수 있습니다. 또한 동적 사용자 인증을 위해 FastMCP의 OAuth 프록시 기능을 사용할 수 있습니다.

  {
    "mcpServers": {
      "google-ads-mcp": {
        "httpUrl":"http://localhost:8080/mcp",
        "env": {
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"                        
        }
      }
    }
  }

• 옵션 2: 애플리케이션 기본 자격 증명 방법

  PATH_TO_CREDENTIALS_JSON을 이전 단계에서 복사한 경로로 바꾸세요.

  또한 env 객체에 GOOGLE_CLOUD_PROJECT 속성을 추가하는 것이 좋습니다. 다음 예제에서 YOUR_PROJECT_ID를 Google Cloud 프로젝트의 프로젝트 ID로 바꾸세요.

  {
    "mcpServers": {
      "google-ads-mcp": {
        "command": "pipx",
        "args": [
          "run",
          "--spec",
          "git+https://github.com/googleads/google-ads-mcp.git",
          "google-ads-mcp"
        ],
        "env": {
          "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
        }
      }
    }
  }

• 옵션 3: Python 클라이언트 라이브러리 방법

  {
    "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_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
        }
      }
    }
  }

로그인 고객 ID

관리자 계정을 통해 고객 계정에 액세스하는 경우 설정 파일에 관리자 계정의 고객 ID를 추가해야 합니다.

자세한 내용은 여기를 참조하세요.

최종 파일은 다음과 같습니다:

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID"
      }
    }
  }
}

기타 MCP 클라이언트(Claude Code, Cursor, VS Code 등)

mcpServers 블록 형식은 모든 MCP 클라이언트에서 동일합니다. 위에 표시된 구성을 클라이언트의 적절한 설정 파일에 추가하세요(예: Claude Code의 경우 ~/.claude/settings.json, Cursor의 경우 .cursor/mcp.json, Copilot이 포함된 VS Code의 경우 .vscode/mcp.json).

Google Cloud Platform에 배포

이 MCP 서버를 로컬에서 호스팅하는 대신 Google Cloud Run 또는 기타 클라우드 기반 인프라에서 호스팅할 수 있습니다. 이는 여러 에이전트 간에 서버를 공유하거나 웹 서비스로 실행하려는 경우 유용합니다.

이는 OAuth 프록시(위 옵션 #1)를 통한 OAuth 클라이언트 ID 및 클라이언트 시크릿 쌍을 사용한 인증만 지원합니다.

전제 조건

1. Google Cloud 프로젝트.

2. gcloud CLI가 설치, 인증 및 활성 프로젝트가 설정되어 있어야 합니다.

   gcloud config set project YOUR_PROJECT_ID

1단계: Docker 이미지 빌드 및 푸시

Cloud Build를 사용하여 Docker를 로컬에 설치하지 않고도 이미지를 빌드하고 Artifact Registry에 푸시할 수 있습니다.

1. Artifact Registry에 저장소 생성:

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

2. 이미지 빌드 및 제출:

   gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .

   YOUR_PROJECT_ID를 Google Cloud 프로젝트 ID로 바꾸세요.

2단계: Google Cloud Run에 배포

필요한 환경 변수를 설정했는지 확인하세요:

• GOOGLE_PROJECT_ID: 귀하의 Google Cloud 프로젝트 ID입니다.

• GOOGLE_ADS_DEVELOPER_TOKEN: MCP 서버가 사용할 개발자 토큰입니다(위 참조).

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: MCP 서버가 사용할 OAuth 클라이언트 ID입니다.

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: MCP 서버가 사용할 OAuth 클라이언트 시크릿입니다.

• GOOGLE_ADS_MCP_BASE_URL: MCP 서버에 접근할 수 있는 기본 URL입니다. 이는 첫 번째 배포 후 Google Cloud Run에서 자동으로 할당됩니다. 배포 후 환경 변수를 업데이트할 수 있습니다.

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: (프로덕션 권장) Cloud Run 인스턴스 간에 사용되는 영구 JWT 서명 키입니다.

• GOOGLE_ADS_MCP_STORAGE_TYPE: (프로덕션 권장) 인스턴스 간 OAuth 토큰을 유지하기 위한 스토리지 백엔드입니다. VPC 커넥터가 필요 없는 Application Default Credentials를 통해 Firestore를 사용하려면 firestore로 설정하고, GOOGLE_ADS_MCP_STORAGE_REDIS_URL과 함께 redis로 설정합니다.

  firestore를 사용하려면 세 가지가 필요합니다: 추가 기능이 설치된 이미지를 빌드하고(Dockerfile을 uv pip install --system .[firestore]로 변경), 프로젝트에 Firestore 데이터베이스를 생성하고(자동으로 프로비저닝되지 않음), Cloud Run 서비스 계정에 roles/datastore.user를 부여합니다. 항목이 자동으로 만료되지 않는다는 점에 유의하세요: 저장소는 읽기 시 만료된 항목을 필터링하지만 삭제하지 않으며, expires_at이 문자열로 기록되므로 Firestore TTL 정책으로도 수집할 수 없습니다. 장기 실행 배포의 경우 주기적인 정리 작업을 계획하세요. Redis는 자체적으로 항목을 만료시킵니다.

• FASTMCP_HOST: FastMCP가 모든 IP 주소의 연결을 허용하도록 0.0.0.0으로 설정합니다.

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=YOUR_JWT_SIGNING_KEY,GOOGLE_ADS_MCP_STORAGE_TYPE=firestore,FASTMCP_HOST=0.0.0.0"

3단계: MCP 클라이언트 구성

배포가 완료되면 MCP 클라이언트 구성을 업데이트하여(https://antigravity.google/docs/mcp 문서 참조) Cloud Run URL을 사용합니다.

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

사용해 보기

MCP 클라이언트를 실행합니다. 사용 가능한 서버 목록에 google-ads-mcp가 표시되어야 합니다.

시작하는 데 도움이 되는 몇 가지 샘플 프롬프트입니다:

• 서버가 무엇을 할 수 있는지 물어보기:

  what can the 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?

고객 ID 참고 사항

에이전트는 대부분의 프롬프트에 대해 고객 ID가 필요하며 이를 요청할 것입니다. 여러 고객 간에 이동하는 경우 프롬프트에 고객 ID를 포함하는 것이 더 간단할 수 있습니다.

How many active campaigns do I have for customer id 1234567890

기여하기

기여를 환영합니다! 기여 가이드를 참조하세요.