# google-ads-mcp: Kết nối Google Ads với AI — hướng dẫn cài đặt và dùng

> google-ads-mcp là MCP server kết nối các LLM hoặc AI agent với Google Ads API. Bạn có thể truy vấn dữ liệu, xem metadata, liệt kê tài khoản và thực hiện một số thao tác quản lý asset, label. Cài đặt cần Python, Google Cloud, quyền Google Ads và cấu hình MCP client nên phù hợp hơn với người có nền tảng kỹ thuật.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-12 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/google-ads-mcp-ket-noi-google-ads-voi-ai

google-ads-mcp là một MCP server kết nối AI agent với Google Ads API. Nhờ đó, bạn có thể yêu cầu AI truy vấn thông tin tài khoản, tìm hiểu cấu trúc tài nguyên, xem chỉ số và thực hiện một số thao tác quản lý asset hoặc label trong Google Ads.

Repo phù hợp với đội marketing, chủ shop, nhân viên chạy quảng cáo và developer muốn dùng ngôn ngữ tự nhiên để làm việc với dữ liệu Google Ads. Điểm đáng giá nhất là các thao tác ghi dữ liệu đều có quy trình Propose & Confirm, giúp bạn xem trước thay đổi và xác nhận rõ ràng trước khi tài khoản bị chỉnh sửa.

Repo dùng Python, yêu cầu Python từ 3.10. Repo hiện có khoảng 1169 sao và 369 fork, dùng giấy phép Apache-2.0. Tuy nhiên, đây không phải công cụ cài xong là dùng ngay như một ứng dụng độc lập. Bạn còn phải bật Google Ads API, cấu hình thông tin xác thực và nối server với một MCP client.

```repo
- repo | googleads/google-ads-mcp
- kind | MCP server
- desc | MCP server giúp AI và agent truy vấn, đọc metadata và quản lý một số tài nguyên trong Google Ads API.
- stars | 1.2k
- lang | Python
- license | Apache-2.0
```

## google-ads-mcp làm được gì

### Truy vấn dữ liệu Google Ads bằng câu lệnh tự nhiên

Tool `search` truy vấn thông tin tài khoản bằng GAQL. Bạn có thể dùng AI để hỏi về chiến dịch, nhóm quảng cáo hoặc các trường dữ liệu cần báo cáo mà không phải tự viết toàn bộ quy vấn.

Lợi ích thực tế là nhân viên marketing có thể bắt đầu từ câu hỏi bằng tiếng Việt hoặc tiếng Anh, sau đó nhờ agent chuyển yêu cầu thành truy vấn phù hợp. Kết quả vẫn phụ thuộc vào quyền truy cập và cách MCP client gửi yêu cầu.

### Tìm hiểu cấu trúc tài nguyên và trường dữ liệu

Tool `get_resource_metadata` trả về metadata của một loại tài nguyên trong Google Ads API, chẳng hạn `campaign`. Tool này giúp bạn biết tài nguyên có những trường nào trước khi tạo truy vấn.

Các resource `discovery-document`, `metrics`, `segments` và `release-notes` cũng giúp LLM hiểu bề mặt API, chỉ số và phân đoạn có thể sử dụng.

### Liệt kê các tài khoản có thể truy cập

Tool `list_accessible_customers` trả về ID của những customer mà người xác thực có thể truy cập trực tiếp. Tính năng này hữu ích khi một người làm việc với nhiều tài khoản hoặc cần xác định đúng customer ID trước khi truy vấn.

### Tạo asset cho quảng cáo

Tool `create_asset` hỗ trợ nhiều loại asset như văn bản, hình ảnh, video YouTube, sitelink, callout và structured snippet. Một số loại khác có thể được truyền qua `extra_params`.

Ở chế độ local `stdio`, tool hỗ trợ đường dẫn file hình ảnh qua `image_asset_path`. Với triển khai HTTP từ xa, README yêu cầu dùng dữ liệu hình ảnh dạng base64 qua `image_asset_data`.

### Tải video lên YouTube để dùng cho asset

Tool `upload_video_asset` tải video local lên YouTube thông qua Google Ads API bằng background task. Tính năng này chỉ được hỗ trợ trong local `stdio` mode.

### Quản lý label và liên kết label

`manage_labels` có thể tạo, cập nhật và xóa label trong tài khoản. `manage_label_associations` có thể tạo hoặc xóa liên kết label với `CAMPAIGN`, `CUSTOMER`, `AD_GROUP` và `AD_GROUP_CRITERION`.

### Có thể giới hạn tool theo nhu cầu

Server dùng file `tools_config.yaml` để bật, tắt từng nhóm hoặc từng tool, đồng thời đổi tiền tố namespace. Mặc định package đi kèm file cấu hình bật toàn bộ tool.

Nếu muốn triển khai chỉ đọc, bạn có thể tắt nhóm `labels` và `assets`. Server tìm file cấu hình theo thứ tự: đường dẫn trong `GOOGLE_ADS_MCP_TOOLS_CONFIG`, file `tools_config.yaml` ở thư mục hiện tại, rồi đến file mặc định trong package.

### Bảo vệ thao tác ghi bằng Propose & Confirm

Các tool ghi dữ liệu gồm `create_asset`, `upload_video_asset`, `manage_labels` và `manage_label_associations` đều dùng quy trình hai bước.

Bước đề xuất chạy với `validate_only=True` mặc định. Server kiểm tra thao tác, thực hiện dry run ở Google Ads API khi được hỗ trợ, rồi trả về `change_items` và `checksum`.

Bước xác nhận phải dùng `validate_only=False`, truyền lại đúng tham số, đúng `customer_id` và `checksum` của bước trước sau khi người dùng chấp thuận. Nếu checksum bị thiếu hoặc không khớp, server từ chối trước khi thay đổi tài khoản.

## Cần chuẩn bị gì

Bạn cần máy có Python từ phiên bản 3.10. Repo là project Python và README hướng dẫn sử dụng `pipx` để chạy package.

Bạn cần một Google Cloud project và phải bật Google Ads API trong project đó. Tài khoản dùng xác thực cũng phải có quyền truy cập vào Google Ads account hoặc property tương ứng.

Nếu dùng Application Default Credentials, credential phải có scope:

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

Bạn cũng cần một MCP client để kết nối server, chẳng hạn Antigravity, Antigravity IDE hoặc Codex. README có ví dụ cấu hình cho các client này.

Nếu chạy FastMCP OAuth Proxy, bạn cần Google Cloud OAuth 2.0 Client ID và Client Secret. Một số biến môi trường như khóa ký JWT, loại storage và đường dẫn storage là tùy chọn, tùy cách triển khai.

Nếu dùng triển khai local WSL và Podman, bạn cần WSL, Podman và một file môi trường riêng chứa thông tin Google Ads và OAuth. README không nêu yêu cầu phần cứng đặc biệt hay GPU.

## Cài đặt từng bước

```steps
- Chuẩn bị Python và pipx | Đảm bảo máy dùng Python từ 3.10 và có pipx
- Bật Google Ads API | Kích hoạt API trong Google Cloud project
- Cấu hình credential | Chọn OAuth Proxy, ADC hoặc Python client library
- Chạy server | Dùng pipx, MCP client hoặc Podman tùy mô hình triển khai
- Kết nối MCP client | Thêm server vào Antigravity hoặc Codex
```

### Chuẩn bị Python và pipx

README yêu cầu cài `pipx`, nhưng phần được cung cấp không ghi lệnh cài pipx cụ thể. Bạn nên cài pipx theo tài liệu chính thức của pipx, sau đó mở terminal mới để lệnh được nhận diện.

Nếu muốn chạy đúng một phiên bản package đã phát hành trên PyPI, README dùng lệnh sau:

```bash
pipx run --spec "google-ads-mcp==X.Y.Z" google-ads-mcp
```

`X.Y.Z` là placeholder cho phiên bản bạn chọn. Không nên gõ nguyên placeholder nếu chưa thay bằng số phiên bản thật.

Để chạy trạng thái mới nhất từ repository, ví dụ cấu hình MCP client của README dùng package trực tiếp từ GitHub:

```bash
pipx run --spec "git+https://github.com/googleads/google-ads-mcp.git" google-ads-mcp
```

README không cung cấp một lệnh cài local hoàn chỉnh cho source checkout. Repo có `pyproject.toml` và `Dockerfile`, nên bạn có thể xem hai file này nếu muốn triển khai từ source hoặc bằng container.

### Bật Google Ads API

Trong Google Cloud project, bật Google Ads API trước khi server thực hiện request. Nếu API chưa bật, server có thể chạy nhưng các thao tác gọi Google Ads sẽ thất bại.

Bạn cần xác định đúng project đang dùng cho credential và MCP client. Khi cấu hình ví dụ cho client, README dùng biến `GOOGLE_PROJECT_ID` hoặc `GOOGLE_CLOUD_PROJECT` tùy phương án.

### Cấu hình bằng Application Default Credentials

Sau khi có OAuth desktop hoặc web client và đã tải client JSON, README đưa lệnh sau để thiết lập ADC bằng user credentials:

```bash
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
```

Thay `YOUR_CLIENT_JSON_FILE` bằng đường dẫn file JSON thật. Terminal sẽ mở quy trình đăng nhập và cấp quyền. Bạn cần dùng tài khoản có quyền trên Google Ads account.

Nếu dùng service account impersonation, README đưa lệnh:

```bash
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
```

Thay `SERVICE_ACCOUNT_EMAIL` bằng email service account thật. Khi lệnh hoàn tất, hãy lưu đường dẫn được in ra:

```text
Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]
```

Đây là đường dẫn sẽ được dùng trong cấu hình MCP client.

### Cấu hình bằng FastMCP OAuth Proxy

OAuth Proxy phù hợp khi server chạy như web service và nhiều client cần xác thực động. Bạn cần đặt các biến sau trong môi trường của tiến trình server:

```bash
GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=your-client-id
GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=your-client-secret
```

`GOOGLE_ADS_MCP_BASE_URL` là tùy chọn và mặc định là `http://localhost:8080`. `GOOGLE_ADS_MCP_JWT_SIGNING_KEY` dùng để ký FastMCP JWT token khi có nhiều instance hoặc deployment.

README cũng hỗ trợ các lựa chọn storage `filetree`, `redis`, `firestore` hoặc `memory` qua `GOOGLE_ADS_MCP_STORAGE_TYPE`. Backend Redis cần cài `py-key-value-aio[redis]`; backend Firestore cần cài `google-ads-mcp[firestore]`.

Khi các biến OAuth Proxy được đặt, server tự chuyển sang transport `streamable-http` thay vì `stdio`. MCP client sẽ kết nối đến endpoint như `http://localhost:8080/mcp`.

### Chạy bằng WSL và Podman

README mô tả triển khai bằng rootless Podman trong WSL. Từ thư mục repository, build image bằng lệnh:

```bash
podman build --tag localhost/google-ads-mcp:latest --file Dockerfile .
```

Quadlet mẫu trong README dùng endpoint loopback, file môi trường riêng và volume riêng cho OAuth state:

```ini
[Container]
Image=localhost/google-ads-mcp:latest
PublishPort=127.0.0.1:8080:8080
EnvironmentFile=/absolute/host/path/google-ads-mcp.env
Volume=google-ads-mcp-oauth.volume:/var/lib/google-ads-mcp:rw
ReadOnly=true
NoNewPrivileges=true
DropCapability=all
```

Thay `/absolute/host/path/google-ads-mcp.env` bằng đường dẫn thật. File môi trường không nằm trong volume OAuth và không được commit vào repository. Nếu chỉ chạy agent local, nên publish port trên loopback như ví dụ.

### Thêm server vào Codex

Sau khi server HTTP đã chạy, README dùng hai lệnh sau để thêm và đăng nhập:

```bash
codex mcp add google_ads --url http://localhost:8080/mcp
codex mcp login google_ads
```

Lệnh đầu đăng ký endpoint. Lệnh thứ hai bắt đầu quy trình xác thực. Nếu server không chạy ở cổng 8080, thay URL bằng endpoint thật.

### Thêm server vào Antigravity

Với Streamable HTTP, cấu hình Antigravity dùng khóa `serverUrl`, không dùng `httpUrl` theo ghi chú của README:

```json
{
  "mcpServers": {
    "google-ads-mcp": {
      "serverUrl": "http://localhost:8080/mcp"
    }
  }
}
```

Sau khi xác thực, client nên nhìn thấy các tool namespaced như `assets_create_asset`, `customers_list_accessible_customers`, `labels_manage_labels`, `metadata_get_resource_metadata` và `search_search`.

### Dùng ADC trực tiếp trong cấu hình client

Nếu chọn cách để MCP client tự khởi động server, README đưa cấu hình sau:

```json
{
  "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"
      }
    }
  }
}
```

Thay `PATH_TO_CREDENTIALS_JSON` và `YOUR_PROJECT_ID` bằng giá trị thật. README lưu ý cách này có mức cô lập credential thấp hơn server-managed Streamable HTTP khi nhiều client dùng chung server.

Nếu bạn đã có file `google-ads.yaml` hoạt động từ Google Ads API Python client library, README cho biết có thể tái sử dụng file này và đổi `get_googleads_client()` trong `utils.py` sang phương thức `load_from_storage()`.

## Kiểm tra đã chạy được chưa

Cách kiểm tra đầu tiên là xem MCP client có kết nối được đến endpoint hay không. Với triển khai HTTP, endpoint mẫu là `http://localhost:8080/mcp`. Với Codex, sau khi chạy lệnh login, client cần nhận diện server `google_ads`.

Sau khi kết nối, danh sách tool phải xuất hiện. Với cấu hình namespace mặc định trong triển khai được mô tả, bạn có thể thấy các tên như:

```text
assets_create_asset
assets_upload_video_asset
customers_list_accessible_customers
labels_manage_label_associations
labels_manage_labels
metadata_get_resource_metadata
search_search
```

Bạn cũng có thể gọi `list_accessible_customers`. Nếu credential và quyền đúng, tool sẽ trả về customer ID mà người dùng có thể truy cập trực tiếp.

Để kiểm tra tool ghi dữ liệu an toàn, bắt đầu bằng một yêu cầu đề xuất với `validate_only=True`. Kết quả cần có các `change_items` và `checksum`. Chưa nên xác nhận nếu bạn chưa kiểm tra đúng customer ID, tham số và nội dung thay đổi.

Nếu file cấu hình tool được chỉ định qua `GOOGLE_ADS_MCP_TOOLS_CONFIG` nhưng file bị thiếu hoặc không hợp lệ, server phải báo lỗi và không khởi động. Đây là dấu hiệu cấu hình cần sửa, không phải lỗi quyền Google Ads đơn thuần.

## Dùng vào việc thật

### Chủ shop muốn xem nhanh tình trạng quảng cáo

Chủ shop có thể kết nối MCP client rồi hỏi: `Hãy liệt kê các customer ID mà tài khoản hiện tại có thể truy cập.` Sau khi biết customer ID, có thể yêu cầu: `Dùng search để tổng hợp thông tin các campaign trong tài khoản này và cho biết những trường dữ liệu bạn đang dùng.`

Server dùng `list_accessible_customers`, `get_resource_metadata` và `search` để lấy dữ liệu. Kết quả giúp chủ shop bắt đầu kiểm tra tài khoản mà không phải tự mở tài liệu API hoặc viết GAQL từ đầu.

### Nhân viên marketing cần tìm trường dữ liệu cho báo cáo

Nhân viên marketing có thể hỏi: `Hãy dùng get_resource_metadata cho resource campaign và giải thích những field phù hợp để lập báo cáo.` Sau đó hỏi tiếp: `Dựa trên các field đó, hãy tạo yêu cầu search để lấy thông tin campaign.`

Cách này phù hợp khi người dùng biết mình muốn báo cáo gì nhưng chưa biết tên resource, field hoặc cấu trúc truy vấn. Resource `metrics` và `segments` cũng giúp agent tìm hiểu các chỉ số và phân đoạn có trong Google Ads API.

### Đội quảng cáo muốn tạo asset nhưng vẫn kiểm soát thay đổi

Khi cần tạo một sitelink hoặc callout, người dùng có thể yêu cầu: `Đề xuất tạo asset cho customer ID này với nội dung sau... Hãy chỉ validate, chưa ghi thay đổi.`

Server sẽ chạy bước đề xuất và trả về `change_items` cùng `checksum`. Người dùng kiểm tra nội dung, đúng tài khoản và đúng tham số trước khi yêu cầu xác nhận bằng `validate_only=False` với checksum tương ứng.

### Developer muốn dựng server dùng chung cho nhiều client

Developer có thể build image bằng Podman, chạy endpoint Streamable HTTP tại loopback rồi kết nối Codex và Antigravity đến cùng endpoint. Credential OAuth được giữ ở tiến trình server thông qua file môi trường riêng, còn các client chỉ cần endpoint và quy trình OAuth của mình.

Cách này phù hợp với nhóm có nhiều MCP client. README khuyến nghị tách file môi trường khỏi repository và volume lưu OAuth state, đồng thời không bật `stateless_http` trên endpoint dùng chung vì tùy chọn đó loại bỏ kênh GET legacy.

> Hãy xem trước mọi thay đổi Google Ads, rồi mới xác nhận bằng checksum.
>
> — Ông T

## Lỗi hay gặp và cách xử lý

### Python hoặc pipx không đúng môi trường

Nếu terminal báo không tìm thấy `pipx` hoặc package không chạy, hãy kiểm tra pipx đã được cài và mở terminal mới. Đảm bảo Python đáp ứng yêu cầu từ 3.10. README không cung cấp lệnh cài pipx cụ thể, nên cần theo tài liệu của pipx.

### Google Ads API chưa được bật

Nếu credential có vẻ đúng nhưng request đến Google Ads thất bại, kiểm tra Google Ads API đã được bật trong đúng Google Cloud project chưa. Cũng kiểm tra `GOOGLE_PROJECT_ID` hoặc project được dùng khi tạo ADC có trùng với project đã bật API không.

### Thiếu scope hoặc không có quyền trên customer

ADC phải có scope `https://www.googleapis.com/auth/adwords`. Người đăng nhập cũng phải có quyền với Google Ads account hoặc property. Nếu truy cập qua manager account, truyền `login_customer_id` trong tool call hoặc đặt `GOOGLE_ADS_LOGIN_CUSTOMER_ID` trong settings; giá trị truyền trong từng lần gọi được ưu tiên hơn.

### MCP client dùng sai URL hoặc sai khóa cấu hình

Với Streamable HTTP, endpoint mẫu là `http://localhost:8080/mcp`. Antigravity 2.8.1 và Antigravity IDE 2.5.5 yêu cầu khóa `serverUrl`; dùng `httpUrl` theo cấu hình cũ có thể không hoạt động.

Nếu dùng Codex, chạy lại `codex mcp add google_ads --url http://localhost:8080/mcp` với URL đúng rồi thực hiện `codex mcp login google_ads`.

### File cấu hình tool bị thiếu hoặc sai

Nếu đặt `GOOGLE_ADS_MCP_TOOLS_CONFIG` đến một file không tồn tại, hoặc file YAML không hợp lệ, server sẽ fail khi khởi động. Kiểm tra đường dẫn, cú pháp và quyền đọc file. Nếu chưa cần tùy chỉnh, có thể bỏ biến môi trường để server dùng file mặc định trong package.

### Đưa nhầm secret vào MCP client hoặc repository

Không đặt OAuth client secret, signing key hay storage key vào cấu hình client nếu server-managed Streamable HTTP đã được dùng. File môi trường nên nằm ngoài repository, giới hạn quyền truy cập và không commit. Với triển khai local, chỉ publish cổng trên loopback khi endpoint không cần truy cập từ mạng khác.

## Có nên dùng không

google-ads-mcp đáng dùng nếu bạn đã sử dụng MCP client và muốn AI làm việc trực tiếp với Google Ads API. Bộ tool có cả đọc dữ liệu, metadata, resource báo cáo và một số thao tác quản lý asset, label. Quy trình Propose & Confirm là điểm mạnh lớn vì giảm nguy cơ ghi nhầm thay đổi vào tài khoản.

Repo cũng phù hợp cho developer cần triển khai server HTTP dùng chung. Việc có thể giới hạn namespace, tắt nhóm ghi dữ liệu và chọn OAuth Proxy hoặc ADC giúp bạn điều chỉnh theo mức độ cô lập credential.

Giới hạn là phần cài đặt không đơn giản. Bạn phải quản lý Python, pipx, Google Cloud project, API, scope, credential, customer ID và MCP client. README được cung cấp cũng không trình bày đầy đủ lệnh cài pipx hoặc toàn bộ quy trình chạy local từ source.

Nếu chỉ cần xem báo cáo bằng giao diện Google Ads, công cụ này có thể quá kỹ thuật. Nếu cần tự động hóa nhiều loại thao tác ngoài các tool được liệt kê, bạn phải kiểm tra phạm vi Google Ads API và phần code trong repo trước khi chọn. Với dữ liệu nhạy cảm hoặc nhiều người dùng, nên ưu tiên server-managed HTTP, tách secret khỏi client và bật cấu hình chỉ đọc nếu chưa cần thao tác ghi.

## Câu hỏi thường gặp

### google-ads-mcp có miễn phí không?

Repo dùng giấy phép Apache-2.0. Tuy vậy, tư liệu không khẳng định toàn bộ chi phí liên quan đến Google Cloud, Google Ads API, hạ tầng OAuth, Redis, Firestore hoặc máy chủ đều bằng 0.

### Có cần GPU để chạy không?

README không nêu yêu cầu GPU hay phần cứng đặc biệt. Repo là MCP server Python và có thể chạy local bằng stdio hoặc triển khai HTTP bằng Podman theo hướng dẫn.

### Có chạy được trên Windows không?

Tư liệu được cung cấp không xác nhận trực tiếp hỗ trợ Windows. README mô tả triển khai local bằng rootless Podman trong WSL, nên phần triển khai đó cần WSL và Podman.

### Có cần tài khoản Google Ads không?

Có. Credential phải thuộc người dùng có quyền truy cập Google Ads account hoặc property. Nếu truy cập qua manager account, bạn có thể cần thêm login customer ID.

### Dữ liệu và secret có an toàn không?

Server sẽ đưa dữ liệu cho LLM hoặc agent mà bạn kết nối. README khuyến nghị giữ credential ngoài cấu hình MCP client, để file môi trường ngoài repository, giới hạn quyền truy cập và không commit file này.

### Có thể chỉ cho phép đọc dữ liệu không?

Có. Bạn có thể dùng `tools_config.yaml` và đặt `labels: false` cùng `assets: false` để tắt các nhóm ghi dữ liệu, tạo triển khai chỉ đọc.

### Thao tác tạo asset có ghi ngay vào tài khoản không?

Không mặc định. Các tool ghi dùng quy trình Propose & Confirm: bước đầu validate và trả về change items cùng checksum; bước xác nhận phải truyền đúng tham số, customer ID và checksum sau khi được chấp thuận.
