google-ads-mcp: Kết nối Google Ads với AI — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về googleads/google-ads-mcp — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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 →

Tóm tắt nhanh
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.
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.
googleads/google-ads-mcp
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.
I.google-ads-mcp làm được gì
A.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.
B.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.
C.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.
D.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.
E.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.
F.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.
G.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.
H.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.
II.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:
https://www.googleapis.com/auth/adwordsBạ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.
III.Cài đặt từng bước
- Chuẩn bị Python và pipxĐảm bảo máy dùng Python từ 3.10 và có pipx
- Bật Google Ads APIKích hoạt API trong Google Cloud project
- Cấu hình credentialChọn OAuth Proxy, ADC hoặc Python client library
- Chạy serverDùng pipx, MCP client hoặc Podman tùy mô hình triển khai
- Kết nối MCP clientThêm server vào Antigravity hoặc Codex
A.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:
pipx run --spec "google-ads-mcp==X.Y.Z" google-ads-mcpX.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:
pipx run --spec "git+https://github.com/googleads/google-ads-mcp.git" google-ads-mcpREADME 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.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.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:
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_FILEThay 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:
gcloud auth application-default login \
--impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
--scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platformThay 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:
Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]Đây là đường dẫn sẽ được dùng trong cấu hình MCP client.
D.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:
GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=your-client-id
GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=your-client-secretGOOGLE_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.
E.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:
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:
[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=allThay /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ụ.
F.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:
codex mcp add google_ads --url http://localhost:8080/mcp
codex mcp login google_adsLệ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.
G.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:
{
"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.
H.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:
{
"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().
IV.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ư:
assets_create_asset
assets_upload_video_asset
customers_list_accessible_customers
labels_manage_label_associations
labels_manage_labels
metadata_get_resource_metadata
search_searchBạ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.
V.Dùng vào việc thật
A.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.
B.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.
C.Độ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.
D.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
VI.Lỗi hay gặp và cách xử lý
A.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.
B.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.
C.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.
D.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.
E.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.
F.Đư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.
VII.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.


