# google-ads-mcp: cho AI đọc và quản lý tài khoản Google Ads — hướng dẫn cài đặt và dùng

> google-ads-mcp là một MCP server viết bằng Python, nằm trong tổ chức googleads trên GitHub, giúp trợ lý AI nói chuyện trực tiếp với Google Ads API. Bạn dùng nó để hỏi số liệu chiến dịch bằng ngôn ngữ thường, và nhờ AI tạo asset hoặc gắn nhãn sau khi bạn duyệt. Cài không quá khó nếu bạn quen terminal, nhưng phải bật API và cấu hình thông tin đăng nhập Google, nên cần kiên nhẫn ở khâu này.

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

google-ads-mcp là một MCP server, tức là một "cổng nối" để trợ lý AI (như Codex hay Antigravity) đọc và thao tác với tài khoản Google Ads của bạn thông qua Google Ads API. Repo nằm trong tổ chức googleads trên GitHub, viết bằng Python, giấy phép Apache-2.0, hiện có khoảng 1166 sao và 368 fork, và vẫn được cập nhật trong vài tháng gần đây.

Vấn đề nó giải quyết rất đời thường: số liệu quảng cáo nằm trong giao diện Google Ads, muốn hỏi "chiến dịch nào tuần này tốn tiền mà không ra đơn?" bạn phải tự bấm lọc, xuất báo cáo, xem từng tab. Có cổng nối này, bạn gõ câu hỏi cho AI, AI gọi các công cụ của server để lấy dữ liệu về và trả lời.

Người nên dùng: người chạy quảng cáo, nhân viên marketing, chủ shop có tài khoản Google Ads, và lập trình viên muốn dựng trợ lý AI cho đội quảng cáo. Điểm đáng giá nhất là cơ chế an toàn "Đề xuất rồi mới Xác nhận" cho mọi thao tác ghi: AI không thể âm thầm sửa tài khoản của bạn.

```repo
- repo | googleads/google-ads-mcp
- kind | MCP server
- desc | MCP server chính thức của Google Ads: cho trợ lý AI truy vấn tài khoản quảng cáo, xem metadata, tạo asset và gắn nhãn, có bước xác nhận trước khi ghi.
- stars | 1.2k
- lang | Python
- license | Apache-2.0
```

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

Server cung cấp một bộ công cụ (tools) và vài tài nguyên (resources) để AI sử dụng.

### Các công cụ chính

- **search**: truy vấn thông tin tài khoản bằng GAQL (ngôn ngữ truy vấn của Google Ads). Bạn không cần tự viết GAQL, AI sẽ viết giúp từ câu hỏi thường của bạn.
- **get_resource_metadata**: cho AI biết một loại đối tượng (ví dụ "campaign") có những trường dữ liệu nào để truy vấn. Nhờ vậy AI ít đoán sai tên trường.
- **list_accessible_customers**: liệt kê ID các tài khoản khách hàng mà người đăng nhập truy cập được. Hữu ích khi bạn quản lý nhiều tài khoản.
- **create_asset**: tạo asset quảng cáo như văn bản, hình ảnh, video YouTube, sitelink, callout, structured snippet và một số loại khác qua tham số `extra_params`.
- **upload_video_asset**: tải một video trên máy lên YouTube qua Google Ads API để dùng làm video asset. Chỉ chạy ở chế độ `stdio` cục bộ.
- **manage_labels**: tạo, sửa, xoá nhãn trong tài khoản.
- **manage_label_associations**: gắn hoặc gỡ nhãn trên chiến dịch, khách hàng, nhóm quảng cáo và tiêu chí nhóm quảng cáo.

### Tài nguyên tham khảo

Server còn cho AI đọc tài liệu discovery của Google Ads API, danh sách metrics, danh sách segments và release notes của phiên bản API mới nhất. Nói đơn giản: AI tự tra "có thể báo cáo theo chỉ số nào" mà không phải đoán.

### Bước "Đề xuất và Xác nhận"

Mọi công cụ ghi (`create_asset`, `upload_video_asset`, `manage_labels`, `manage_label_associations`) chạy hai bước:

1. **Đề xuất** (`validate_only=True`, là mặc định): server kiểm tra thao tác, chạy thử khô với Google Ads API nếu có hỗ trợ, rồi trả về danh sách thay đổi dễ đọc cùng một `checksum` gắn với ID khách hàng và tham số.
2. **Xác nhận** (`validate_only=False`): phải gửi lại đúng tham số cũ, đúng `customer_id`, kèm `checksum` ở bước 1 sau khi bạn đồng ý. Thiếu hoặc sai checksum thì bị từ chối trước khi chạm vào tài khoản.

### Bật tắt công cụ bằng tools_config.yaml

Gói đã kèm sẵn một file `tools_config.yaml` bật hết công cụ, nên chạy ngay không cần cấu hình thêm. Muốn tuỳ chỉnh, server tìm theo thứ tự: đường dẫn trong biến môi trường `GOOGLE_ADS_MCP_TOOLS_CONFIG`, rồi file `tools_config.yaml` ở thư mục hiện tại, rồi bản mặc định đi kèm. Muốn server chỉ đọc, đặt `labels: false` và `assets: false`.

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

Theo tư liệu, bạn cần:

- **Python 3.10 trở lên** (pyproject.toml yêu cầu `>=3.10`).
- **pipx**, công cụ để chạy ứng dụng Python. README hướng dẫn cài pipx theo trang chính thức của nó.
- **Một Google Cloud project** đã bật Google Ads API.
- **Thông tin đăng nhập Google** của người dùng có quyền truy cập tài khoản Google Ads. Credentials phải có scope `https://www.googleapis.com/auth/adwords`.
- **Một MCP client**, README có ví dụ cho Antigravity / Antigravity IDE và Codex.
- Nếu truy cập tài khoản qua tài khoản quản lý (manager), bạn cần ID của tài khoản quản lý đó.

Về hệ điều hành: README mô tả cách chạy trong WSL với Podman, và Dockerfile có sẵn trong repo. README không nói rõ yêu cầu phần cứng. Phần cuối README trong tư liệu mình có bị cắt, nên nếu bạn gặp yêu cầu nào chưa thấy ở đây, hãy mở README gốc trên GitHub để đối chiếu.

```note
Server sẽ đưa dữ liệu tài khoản quảng cáo của bạn cho AI mà bạn kết nối vào (README nói rõ điều này). Chỉ nối với trợ lý bạn tin tưởng, và nếu chưa cần ghi thì đặt `labels: false`, `assets: false` để server chỉ đọc.
```

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

README chia thành bốn việc: cấu hình Python, bật API, cấu hình thông tin đăng nhập, cấu hình MCP client. Dưới đây mình đi theo hướng đơn giản nhất cho người dùng cá nhân: đăng nhập bằng Application Default Credentials (ADC) và để MCP client tự khởi động server.

```steps
- Cài pipx | Công cụ để chạy server Python mà không cần cài thủ công
- Bật Google Ads API | Bật API trong Google Cloud project của bạn
- Tạo thông tin đăng nhập | Dùng gcloud tạo file ADC có scope adwords
- Khai báo trong MCP client | Dán cấu hình JSON, điền đường dẫn file credentials và project ID
- Chọn tài khoản quản lý nếu cần | Đặt login customer ID khi truy cập qua manager
```

### Cài pipx

Làm theo trang cài đặt pipx chính thức mà README dẫn tới (pipx.pypa.io). Sau khi cài xong, mở một cửa sổ terminal mới (PowerShell trên Windows, Terminal trên macOS/Linux) để máy nhận lệnh `pipx`.

README cũng cho biết sau khi một phiên bản được đưa lên PyPI, bạn có thể chạy đúng phiên bản đó thay vì bản mới nhất của repo. Thay `X.Y.Z` bằng số phiên bản thật:

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

Đừng chạy nguyên văn `X.Y.Z`, đó chỉ là chỗ giữ chỗ.

### Bật Google Ads API trong project

Làm theo hướng dẫn của Google (support.google.com/googleapi/answer/6158841) để bật **Google Ads API** trong Google Cloud project của bạn. README chỉ rõ một API này. Bạn bật ở trang thư viện API của Google Cloud, chọn đúng project rồi bấm Enable.

### Tạo thông tin đăng nhập (ADC)

README có ba cách. Mình chọn cách ADC vì gọn. Bạn cần một OAuth client (hướng dẫn tạo ở trang "Manage OAuth Clients" của Google) và tải file JSON của client đó về máy. Rồi chạy lệnh sau, thay `YOUR_CLIENT_JSON_FILE` bằng đường dẫn tới file JSON:

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

Dấu `\` cuối dòng là cách xuống dòng trong shell kiểu Linux/macOS. Trên PowerShell bạn nên gõ cả lệnh trên một dòng. Trình duyệt sẽ mở ra để bạn đăng nhập bằng tài khoản Google có quyền vào tài khoản Google Ads.

Nếu công ty bạn dùng service account, README có cách khác là mượn quyền (impersonation):

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

Lệnh xong sẽ in ra một dòng dạng này. **Hãy chép lại đường dẫn trong ngoặc**, bước sau cần dùng:

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

README còn có cách 3: dùng thư viện Google Ads API cho Python và file `google-ads.yaml` có sẵn. Cách này đòi bạn sửa hàm `get_googleads_client()` trong file `utils.py` để dùng `load_from_storage()`, nên bạn phải có mã nguồn trên máy. Người mới nên tránh cách này.

### Khai báo server trong MCP client

Với Antigravity hoặc Antigravity IDE, README dẫn tới tài liệu MCP của họ (antigravity.google/docs/mcp) để biết file cấu hình nằm đâu. Nội dung cấu hình cho cách ADC như sau. Thay `PATH_TO_CREDENTIALS_JSON` bằng đường dẫn bạn chép ở bước trước và `YOUR_PROJECT_ID` bằng project ID của bạn:

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

Client sẽ tự chạy `pipx run ...` mỗi lần cần server, bạn không phải bật tay. Lưu ý: phần chữ của README khuyên thêm thuộc tính `GOOGLE_CLOUD_PROJECT`, còn ví dụ JSON lại dùng `GOOGLE_PROJECT_ID`. Mình chép đúng theo ví dụ JSON. Trên Windows, đường dẫn trong JSON nên viết dấu `/` hoặc gấp đôi dấu `\\` để không lỗi.

### Chọn tài khoản quản lý nếu cần

Nếu bạn vào tài khoản khách hàng thông qua một tài khoản quản lý, bạn có hai cách theo README: truyền tham số `login_customer_id` mỗi lần gọi công cụ, hoặc đặt `GOOGLE_ADS_LOGIN_CUSTOMER_ID` làm mặc định trong file settings. Nếu có cả hai, tham số mỗi lần gọi được ưu tiên.

### Cách khác: chạy server dạng dịch vụ web

README còn có cách chạy server riêng bằng OAuth proxy của FastMCP, tiện khi nhiều công cụ cùng dùng một server. Cách này cần đặt biến môi trường `GOOGLE_ADS_MCP_OAUTH_CLIENT_ID` và `GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET`. Khi đó server tự chuyển sang giao thức `streamable-http`, địa chỉ mặc định là `http://localhost:8080/mcp`. Cấu hình phía Antigravity chỉ cần:

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

README nhấn mạnh phải dùng khoá `serverUrl`, không dùng `httpUrl` cũ. Với Codex thì thêm và đăng nhập server bằng hai lệnh:

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

README cũng mô tả cách đóng gói bằng Podman trong WSL, với lệnh build như sau (chạy ở thư mục repo sau khi `git clone https://github.com/googleads/google-ads-mcp.git` và `cd google-ads-mcp`):

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

Cách này dành cho người đã quen container. Nếu mới bắt đầu, hãy dùng cách ADC ở trên.

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

Khởi động lại MCP client sau khi sửa cấu hình, rồi vào danh sách MCP server/công cụ của client. Bạn nên thấy server `google-ads-mcp` và các công cụ của nó.

Với cách chạy dịch vụ web, README cho biết sau khi xác thực, cả Codex và Antigravity sẽ liệt kê các công cụ có tiền tố theo nhóm:

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

Rồi thử câu hỏi nhẹ nhàng: "Liệt kê các tài khoản Google Ads mà mình truy cập được." Nếu AI trả về danh sách ID khách hàng, tức là đường đi từ AI tới Google Ads đã thông. README không mô tả thêm kiểu kiểm tra nào khác.

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

### Chủ shop hỏi nhanh hiệu quả chiến dịch

Chị Lan bán mỹ phẩm online, tự chạy quảng cáo, không rành GAQL. Chị mở trợ lý AI đã nối server và nhắn: "Liệt kê các tài khoản Google Ads mình truy cập được, rồi cho mình xem các chiến dịch của tài khoản đầu tiên." AI gọi `list_accessible_customers`, rồi dùng `get_resource_metadata` để biết trường nào có thể hỏi, cuối cùng dùng `search` để lấy dữ liệu. Chị nhận câu trả lời bằng chữ thường thay vì phải xuất báo cáo.

### Nhân viên marketing làm báo cáo tuần

Anh Nam làm marketing cho một công ty dịch vụ, mỗi thứ Hai phải gom số liệu. Anh nhắn: "Với tài khoản này, những chỉ số và segment nào có thể dùng để báo cáo? Gợi ý cho mình một báo cáo tuần theo chiến dịch." AI đọc các resource `metrics` và `segments` rồi đề xuất cột phù hợp, sau đó chạy `search`. Anh tiết kiệm công mò từng tên trường.

> Ghi công cụ nào cho AI cũng được, miễn là nó phải đưa bạn xem trước rồi mới bấm.
>
> — Ông T

### Gắn nhãn hàng loạt, có duyệt trước

Chị Hà quản lý hơn chục chiến dịch và muốn gắn nhãn "Tết" cho các chiến dịch mùa lễ. Chị nhắn: "Tạo nhãn tên Tết rồi gắn vào các chiến dịch này." Ở bước Đề xuất, server trả về danh sách thay đổi và một `checksum`, chưa động vào tài khoản. Chị đọc kỹ, đồng ý, AI mới gửi lại đúng tham số cùng checksum để thực thi. Nếu AI đổi tham số giữa chừng, checksum không khớp và thao tác bị từ chối.

### Lập trình viên bổ sung asset cho quảng cáo

Bạn là dev của một agency, cần thêm sitelink và callout cho khách. Bạn nhờ AI: "Đề xuất tạo hai sitelink và một callout cho tài khoản này, chưa thực hiện." AI gọi `create_asset` ở chế độ `validate_only=True`, bạn xem `change_items`. Chỉ khi bạn duyệt, AI mới xác nhận. Nếu cần ảnh, README nói `image_asset_path` chỉ dùng ở chế độ `stdio` cục bộ, còn triển khai HTTP từ xa phải dùng `image_asset_data` dạng base64.

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

### Server không khởi động hoặc client báo không tìm thấy lệnh

Thường do chưa cài pipx hoặc terminal/client chưa nhận lệnh `pipx`. Cài pipx theo trang chính thức, mở lại terminal, đóng và mở lại MCP client. Kiểm tra Python từ 3.10 trở lên.

### Lỗi quyền hoặc xác thực khi gọi API

Nguyên nhân hay gặp: credentials thiếu scope `https://www.googleapis.com/auth/adwords`, hoặc tài khoản Google bạn đăng nhập không có quyền vào tài khoản Google Ads đó, hoặc chưa bật Google Ads API trong project. Chạy lại lệnh `gcloud auth application-default login` với đủ `--scopes` như README, và kiểm tra `GOOGLE_APPLICATION_CREDENTIALS` trỏ đúng file.

### Truy cập tài khoản con nhưng bị từ chối

Nếu bạn vào qua tài khoản quản lý, hãy cung cấp `login_customer_id` (mỗi lần gọi) hoặc đặt `GOOGLE_ADS_LOGIN_CUSTOMER_ID` làm mặc định. README nêu rõ hai cách này.

### Server báo lỗi khi đọc tools_config.yaml

Theo README, nếu file cấu hình được chỉ định qua `GOOGLE_ADS_MCP_TOOLS_CONFIG` không tồn tại, hoặc bất kỳ file nào được dùng bị sai định dạng, server sẽ báo lỗi và không khởi động. Hãy kiểm tra đường dẫn và cú pháp YAML, hoặc tạm bỏ biến này để dùng bản mặc định.

### Thao tác ghi bị từ chối vì checksum

Đây là hành vi thiết kế, không phải lỗi. Bước Xác nhận phải dùng đúng tham số và `customer_id` như bước Đề xuất, kèm checksum nhận được. Nếu bạn muốn đổi gì đó, hãy chạy lại bước Đề xuất để lấy checksum mới.

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

**Điểm mạnh**

- Do chính tổ chức googleads của Google đăng, nên bám sát Google Ads API.
- Có cơ chế Đề xuất rồi Xác nhận với checksum cho mọi thao tác ghi, rất đáng giá khi đụng tới tiền quảng cáo.
- Có thể tắt hẳn nhóm công cụ ghi để chạy ở chế độ chỉ đọc.
- Hỗ trợ nhiều cách đăng nhập, từ ADC cá nhân đến OAuth proxy cho dùng chung.

**Giới hạn**

- Bộ công cụ ghi hiện chủ yếu là asset và nhãn. Theo README, server không nêu việc sửa ngân sách hay giá thầu, nên đừng kỳ vọng AI tự tối ưu chiến dịch hộ bạn.
- Khâu cấu hình Google Cloud và credentials khá nhiều bước, người chưa quen sẽ mất thời gian.
- Dữ liệu tài khoản được đưa cho AI bạn kết nối, cần cân nhắc chính sách bảo mật của công ty.
- README ghi server thêm một header vào các lệnh gọi API để Google thu thập dữ liệu sử dụng.
- `upload_video_asset` và `image_asset_path` chỉ chạy ở chế độ `stdio` cục bộ.

**Khi nào chọn cách khác:** nếu bạn chỉ cần xem báo cáo định kỳ, giao diện Google Ads hoặc báo cáo có sẵn là đủ. Nếu bạn cần tự động hoá sâu theo logic riêng, có thể gọi thẳng Google Ads API bằng thư viện Python. Còn nếu bạn muốn hỏi đáp số liệu bằng ngôn ngữ thường và có kiểm soát khi ghi, google-ads-mcp là lựa chọn hợp lý.

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

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

Mã nguồn dùng giấy phép Apache-2.0 nên bạn dùng tự do. Tư liệu không nói gì về chi phí khác, như chi phí của MCP client hay mô hình AI bạn nối vào, nên phần đó bạn tự kiểm tra theo công cụ mình dùng.

### Có cần GPU hay máy cấu hình mạnh không?

Tư liệu không nêu yêu cầu phần cứng nào. Server là chương trình Python nhẹ gọi Google Ads API, việc suy luận do trợ lý AI bên phía client đảm nhiệm.

### Chạy được trên Windows không?

README có hướng dẫn triển khai trong WSL bằng Podman và repo có sẵn Dockerfile. Cách chạy bằng pipx cần Python 3.10 trở lên. README không có mục riêng cho Windows thuần, nên bạn thử cách pipx và đối chiếu với README gốc nếu gặp vấn đề.

### Dữ liệu tài khoản quảng cáo của tôi có an toàn không?

README nói rõ server sẽ đưa dữ liệu của bạn cho Agent hoặc LLM mà bạn kết nối vào, nên chỉ nối với trợ lý bạn tin tưởng. Về ghi dữ liệu, các công cụ ghi đều có bước Đề xuất và Xác nhận bằng checksum. Bạn cũng có thể đặt `labels: false` và `assets: false` để chạy chỉ đọc.

### AI có tự ý sửa chiến dịch của tôi được không?

Không thể ghi ngay. Mặc định các công cụ ghi chạy ở chế độ `validate_only=True`, chỉ kiểm tra và trả về danh sách thay đổi. Muốn thực thi phải gửi lại đúng tham số cùng checksum sau khi bạn duyệt, thiếu hoặc sai checksum thì bị từ chối.

### Cần đăng nhập thế nào để server truy cập Google Ads?

README có ba cách: OAuth proxy của FastMCP, Application Default Credentials qua lệnh gcloud, hoặc thư viện Google Ads API cho Python với file google-ads.yaml. Credentials phải có scope `https://www.googleapis.com/auth/adwords` và thuộc người dùng có quyền vào tài khoản Google Ads.

### Tôi quản lý nhiều tài khoản qua tài khoản manager thì làm sao?

Bạn truyền tham số `login_customer_id` khi gọi công cụ, hoặc đặt `GOOGLE_ADS_LOGIN_CUSTOMER_ID` làm mặc định trong file settings. Nếu có cả hai thì tham số mỗi lần gọi được ưu tiên.
