> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chotdeal.vn/llms.txt
> Use this file to discover all available pages before exploring further.

# Kết nối Google Ads & Google Analytics vào Claude bằng MCP

> Hướng dẫn từ số 0: tạo project Google Cloud, lấy khóa, cài server local, cách dùng, quyền truy cập và xử lý lỗi cho Google Ads MCP và Google Analytics MCP (GA4).

<Tip>
  Hướng dẫn cài **2 MCP server chạy local trên máy bạn**: Google Ads MCP và Google Analytics MCP (GA4). Chia 3 phần: cài đặt, cách dùng, và quyền & lỗi. Cả hai đều **chỉ đọc (read-only)** — an toàn để khám phá dữ liệu.
</Tip>

## 6 giá trị bạn sẽ thu thập

Làm theo **Phần A**, ghi lại 6 giá trị bên dưới. Đến Bước 10 bạn điền chúng vào file config là xong.

| Biến                             | Tên                     | Lấy ở đâu                        |
| -------------------------------- | ----------------------- | -------------------------------- |
| `GOOGLE_PROJECT_ID`              | Project ID              | ID project Google Cloud (Bước 1) |
| `client_secret.json`             | File OAuth client       | Tải về ở Bước 4                  |
| `GOOGLE_ADS_DEVELOPER_TOKEN`     | Developer Token         | Ads API Center (Bước 5)          |
| `GOOGLE_ADS_LOGIN_CUSTOMER_ID`   | Login Customer ID (MCC) | ID tài khoản quản lý (Bước 5)    |
| `GA4 Property ID`                | Property ID             | Trong GA Admin (Bước 6)          |
| `GOOGLE_APPLICATION_CREDENTIALS` | Đường dẫn ADC           | Tự sinh ở Bước 8                 |

***

## Phần A — Chuẩn bị trên Google (trên trình duyệt)

<Steps>
  <Step title="Tạo project Google Cloud">
    Project là nơi bật API và tạo khóa đăng nhập cho cả 2 MCP.

    1. Mở trang **Tạo project**, đăng nhập bằng Google account quản lý shop.
    2. Nhập **Project name** (ví dụ `MCP Ads Analytics`), bấm **Create**.
    3. Đợi vài giây, chọn project vừa tạo ở thanh chọn project trên cùng.
    4. Copy **Project ID** (khác tên hiển thị, dạng `mcp-ads-analytics-471203`). Ghi lại làm `GOOGLE_PROJECT_ID`.

    <Card title="Tạo project" icon="square-plus" href="https://console.cloud.google.com/projectcreate">
      Console tạo project Google Cloud
    </Card>
  </Step>

  <Step title="Bật 3 API cần thiết">
    Bật đúng project. Mở lần lượt 3 link dưới rồi bấm nút **Enable** ở mỗi trang.

    1. Kiểm tra thanh trên cùng đang chọn đúng project ở Bước 1.
    2. Mở từng link, bấm **Enable**. Nếu nút hiện **Manage** nghĩa là đã bật rồi.

    <Columns cols={3}>
      <Card title="Google Ads API" icon="bullhorn" href="https://console.cloud.google.com/apis/library/googleads.googleapis.com" />

      <Card title="Analytics Admin API" icon="gear" href="https://console.cloud.google.com/apis/library/analyticsadmin.googleapis.com" />

      <Card title="Analytics Data API" icon="chart-line" href="https://console.cloud.google.com/apis/library/analyticsdata.googleapis.com" />
    </Columns>
  </Step>

  <Step title="Cấu hình màn hình đồng ý OAuth">
    Bước này cho phép app đăng nhập vào tài khoản Google của bạn.

    1. Mở trang **OAuth consent screen**.
    2. Chọn **User type: External**, bấm **Create**.
    3. Điền **App name**, **User support email**, **Developer contact email**, rồi **Save**.
    4. Vào mục **Test users / Audience**, bấm **Add users**, thêm chính email Google của bạn.

    <Warning>
      Để chế độ **Testing** thì khóa đăng nhập (ADC) hết hạn khoảng **7 ngày**, phải đăng nhập lại. Muốn dùng ổn định lâu dài, bấm **Publish app** để chuyển sang **Production**.
    </Warning>
  </Step>

  <Step title="Tạo OAuth client & tải file JSON">
    1. Mở trang **Credentials**.
    2. Bấm **Create Credentials**, chọn **OAuth client ID**.
    3. **Application type** chọn **Desktop app**, đặt tên, bấm **Create**.
    4. Bấm **Download JSON**, lưu vào nơi dễ nhớ, ví dụ `~/google/client_secret.json`.

    <Accordion title="Prompt cho Claude Code" icon="terminal">
      ```text theme={null}
      Tôi vừa tải file client_secret.json về thư mục Downloads. Tạo thư mục ~/google
      rồi di chuyển file vào đó, và cho tôi đường dẫn đầy đủ để dùng cho bước đăng nhập.
      ```
    </Accordion>
  </Step>

  <Step title="Lấy Developer Token & Login Customer ID (Google Ads)">
    1. Cần một **tài khoản MCC** (Manager Account). Chưa có thì tạo mới.
    2. Trong MCC, vào **Tools & Settings**, mở **API Center**.
    3. Copy **Developer token**, ghi lại làm `GOOGLE_ADS_DEVELOPER_TOKEN`.
    4. Token mới thường ở mức **Test**; muốn query tài khoản thật, xin duyệt **Basic access** ngay trong API Center.
    5. Ghi lại **Login Customer ID** = ID của MCC (dạng `123-456-7890`; khi điền config bỏ gạch nối thành `1234567890`).

    <Tip>
      Token mới = mức Test (chỉ query test account). Muốn đọc tài khoản thật, xin duyệt **Basic access** — xem phần **Quyền & Lỗi** bên dưới.
    </Tip>
  </Step>

  <Step title="Lấy Property ID (Google Analytics GA4)">
    1. Mở **Google Analytics**, đăng nhập tài khoản có quyền xem property.
    2. Bấm **Admin** (bánh răng góc dưới trái).
    3. Ở cột **Property**, chọn đúng property rồi mở **Property settings**.
    4. Copy **Property ID** (dạng số như `255854183`). Ghi lại.
    5. Đảm bảo tài khoản của bạn có quyền **Viewer** trở lên với property đó.
  </Step>
</Steps>

***

## Phần B — Cài trên máy (Terminal)

<Steps>
  <Step title="Cài uv và gcloud CLI">
    `uv` để cài server Python; `gcloud` để đăng nhập Google.

    ```bash Terminal theme={null}
    # Cài uv
    curl -LsSf https://astral.sh/uv/install.sh | sh

    # Cài Google Cloud CLI (Homebrew)
    brew install --cask google-cloud-sdk
    ```

    <Accordion title="Prompt cho Claude Code" icon="terminal">
      ```text theme={null}
      Kiểm tra máy đã có uv và gcloud CLI chưa. Cái nào thiếu thì cài giúp và xác nhận version.
      ```
    </Accordion>
  </Step>

  <Step title="Đăng nhập ADC với đủ scope">
    Cả 2 MCP dùng chung một credential. Đăng nhập **một lần** kèm đủ 3 scope, nếu thiếu sẽ làm hỏng cái còn lại. Thay `/path/to/client_secret.json` bằng đường dẫn file ở Bước 4.

    ```bash Terminal theme={null}
    gcloud auth application-default login \
      --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform \
      --client-id-file="/path/to/client_secret.json"
    ```

    1. Trình duyệt mở ra, chọn đúng tài khoản Google, bấm **Allow**.
    2. Terminal in ra dòng **Credentials saved to file: \[...]**. Ghi lại đường dẫn đó làm `GOOGLE_APPLICATION_CREDENTIALS` (thường là `~/.config/gcloud/application_default_credentials.json`).
  </Step>

  <Step title="Cài 2 MCP server (local, từ PyPI)">
    Cài mỗi server vào một venv riêng để chạy thẳng binary local, khởi động tức thì, không phụ thuộc git hay mạng.

    ```bash Terminal theme={null}
    # Google Ads MCP
    uv venv ~/.local/share/google-ads-mcp/venv
    uv pip install --python ~/.local/share/google-ads-mcp/venv/bin/python google-ads-mcp

    # Google Analytics MCP (bản chính thức của Google)
    uv venv ~/.local/share/analytics-mcp/venv
    uv pip install --python ~/.local/share/analytics-mcp/venv/bin/python analytics-mcp
    ```

    <Accordion title="Prompt cho Claude Code" icon="terminal">
      ```text theme={null}
      Cài giúp tôi 2 MCP server vào venv local từ PyPI: google-ads-mcp và analytics-mcp.
      Test mỗi binary bằng MCP initialize handshake để xác nhận chạy được, rồi cho tôi đường dẫn binary đầy đủ.
      ```
    </Accordion>
  </Step>

  <Step title="Khai báo vào config MCP">
    1. Với **Claude Desktop**: Settings → Developer → Local MCP servers → **Edit Config**. Với **Claude Code**: mở file `~/.claude.json`.
    2. Dán khối JSON dưới vào mục `mcpServers`.
    3. Thay các giá trị `YOUR_...` và đường dẫn `/Users/YOU/...` bằng 6 giá trị bạn đã ghi ở Phần A.

    ```json claude_desktop_config.json theme={null}
    {
      "mcpServers": {
        "google-ads-mcp": {
          "command": "/Users/YOU/.local/share/google-ads-mcp/venv/bin/google-ads-mcp",
          "args": [],
          "env": {
            "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
            "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
            "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MCC_ID",
            "GOOGLE_APPLICATION_CREDENTIALS": "/Users/YOU/.config/gcloud/application_default_credentials.json"
          }
        },
        "analytics-mcp": {
          "command": "/Users/YOU/.local/share/analytics-mcp/venv/bin/analytics-mcp",
          "args": [],
          "env": {
            "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
            "GOOGLE_APPLICATION_CREDENTIALS": "/Users/YOU/.config/gcloud/application_default_credentials.json"
          }
        }
      }
    }
    ```

    <Accordion title="Prompt cho Claude Code" icon="terminal">
      ```text theme={null}
      Thêm 2 MCP server (google-ads-mcp, analytics-mcp) trỏ vào binary local vừa cài,
      vào cả ~/.claude.json và claude_desktop_config.json. Điền env: project id,
      developer token, login customer id (MCC), đường dẫn ADC. Giữ nguyên các server và cấu hình có sẵn.
      ```
    </Accordion>
  </Step>

  <Step title="Khởi động lại & kiểm tra">
    1. Thoát hẳn Claude bằng **Cmd+Q**, rồi mở lại (khởi động lại mới nạp server).
    2. Vào **Settings → Developer → Local MCP servers**, thấy 2 server là được.
    3. Mở một task Cowork mới và chạy prompt kiểm tra bên dưới.

    <Accordion title="Prompt kiểm tra" icon="circle-check">
      ```text theme={null}
      Kiểm tra kết nối 2 MCP: liệt kê các tài khoản Google Ads tôi truy cập được,
      và liệt kê các property Google Analytics của tôi. Nếu lỗi thì chẩn đoán giúp.
      ```
    </Accordion>

    <Warning>
      Gặp lỗi `invalid_grant` sau vài ngày? Đó là ADC hết hạn (app OAuth ở chế độ Testing). Chạy lại lệnh đăng nhập ở Bước 8 (giữ đủ 3 scope). Muốn khỏi hết hạn, publish app OAuth sang Production ở Bước 3.
    </Warning>
  </Step>
</Steps>

***

## Dùng 2 MCP để làm gì?

<Tabs>
  <Tab title="Google Ads MCP">
    Đọc dữ liệu quảng cáo qua GAQL. Chỉ đọc, không tự đổi campaign.

    | Tool                        | Công dụng                                                               |
    | --------------------------- | ----------------------------------------------------------------------- |
    | `list_accessible_customers` | Liệt kê tài khoản quảng cáo bạn truy cập được                           |
    | `search`                    | Chạy truy vấn GAQL: campaign, keyword, search term, chi phí, chuyển đổi |
    | `get_resource_metadata`     | Tra đúng tên field cho resource trước khi viết GAQL                     |

    **Resource chính:** `campaign` · `ad_group` · `keyword_view` · `search_term_view` · `customer_client`

    <Accordion title="Chi phí theo campaign">
      Xem chi phí, số chuyển đổi và giá trị chuyển đổi của từng campaign trong 30 ngày qua, sắp theo chi phí giảm dần.
    </Accordion>

    <AccordionGroup>
      <Accordion title="Từ khóa đốt tiền">
        Liệt kê top 20 keyword tốn nhiều tiền nhất mà 0 chuyển đổi trong 30 ngày qua, để tôi cân nhắc tắt.
      </Accordion>

      <Accordion title="Search terms & negative">
        Xem các cụm từ tìm kiếm thực tế (search terms) có click nhưng không ra đơn, gợi ý danh sách negative keyword nên thêm.
      </Accordion>

      <Accordion title="So sánh 2 kỳ">
        So sánh chi phí và số chuyển đổi theo campaign giữa 7 ngày gần nhất và 7 ngày trước đó, chỉ ra campaign nào đang lên hoặc xuống mạnh.
      </Accordion>

      <Accordion title="Hiệu quả theo thiết bị/giờ">
        Phân tích chi phí và tỷ lệ chuyển đổi theo thiết bị và theo khung giờ trong ngày, gợi ý điều chỉnh bid.
      </Accordion>

      <Accordion title="Sức khỏe tài khoản">
        Tổng quan tài khoản 30 ngày: tổng chi phí, CTR, CPC trung bình, tỷ lệ chuyển đổi, và 3 vấn đề đáng lưu ý nhất.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Google Analytics MCP (GA4)">
    Đọc dữ liệu hành vi & chuyển đổi trên website qua Data API + Admin API.

    | Tool                                | Công dụng                                        |
    | ----------------------------------- | ------------------------------------------------ |
    | `get_account_summaries`             | Liệt kê tài khoản & property GA4 của bạn         |
    | `run_report`                        | Báo cáo linh hoạt theo dimension & metric bất kỳ |
    | `run_realtime_report`               | Người đang online trên web ngay lúc này          |
    | `run_funnel_report`                 | Phễu chuyển đổi qua từng bước                    |
    | `get_custom_dimensions_and_metrics` | Xem dimension/metric tùy biến của property       |
    | `list_google_ads_links`             | Các liên kết Google Ads gắn với property         |

    <AccordionGroup>
      <Accordion title="Nguồn traffic ra đơn">
        Trên property GA4 của tôi, cho biết nguồn/kênh (source/medium) nào ra nhiều đơn và doanh thu nhất trong 30 ngày qua.
      </Accordion>

      <Accordion title="Trang sản phẩm hút khách">
        Top 15 trang có nhiều lượt xem và giá trị mua nhất trong 30 ngày qua, kèm tỷ lệ chuyển đổi từng trang.
      </Accordion>

      <Accordion title="Phễu mua hàng">
        Dựng phễu 30 ngày: xem sản phẩm, thêm giỏ, bắt đầu thanh toán, mua thành công. Chỉ ra bước rớt nhiều nhất.
      </Accordion>

      <Accordion title="Đang online lúc này">
        Hiện có bao nhiêu người đang truy cập website, họ đang xem trang nào và đến từ nguồn nào (realtime).
      </Accordion>

      <Accordion title="Thiết bị & khu vực">
        Phân bổ đơn hàng và doanh thu theo loại thiết bị và theo tỉnh/thành trong 30 ngày qua.
      </Accordion>

      <Accordion title="Khách mới vs quay lại">
        So sánh tỷ lệ chuyển đổi và giá trị đơn giữa khách mới và khách quay lại trong 30 ngày qua.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Kết hợp Ads × GA4">
    Ghép chi phí thật từ Ads với doanh thu thật từ GA4 để ra bức tranh đầy đủ.

    <AccordionGroup>
      <Accordion title="ROAS thật theo campaign">
        Ghép chi phí Google Ads với doanh thu GA4 theo từng campaign trong 30 ngày, tính ROAS thật (doanh thu / chi phí), chỉ ra campaign nên tăng ngân sách và campaign nên cắt.
      </Accordion>

      <Accordion title="Ads nói khác GA4?">
        So sánh số chuyển đổi và giá trị mà Google Ads tự báo với doanh thu thật trên GA4 theo campaign, chỉ ra chỗ Ads đang thổi phồng.
      </Accordion>

      <Accordion title="Trả phí vs miễn phí">
        So sánh đóng góp doanh thu giữa traffic trả phí (Ads) và miễn phí (SEO, direct) trong 30 ngày, tính tỷ trọng từng kênh.
      </Accordion>

      <Accordion title="Báo cáo tuần cho team">
        Tạo báo cáo tuần: chi phí Ads, doanh thu GA4, ROAS, top campaign, và 3 đề xuất hành động. Xuất ra bảng gọn để gửi team.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

***

## Quyền truy cập & xử lý lỗi

### Quyền OAuth (scope)

Cả 2 MCP dùng chung một credential ADC. Một lần đăng nhập cấp đủ 3 scope sau. Thiếu scope nào thì MCP tương ứng sẽ báo lỗi quyền.

| Scope                | Dành cho   | Cấp quyền gì                                                 |
| -------------------- | ---------- | ------------------------------------------------------------ |
| `adwords`            | Google Ads | Truy cập Google Ads API. MCP chỉ dùng để **đọc**, không ghi. |
| `analytics.readonly` | Analytics  | Đọc dữ liệu Google Analytics (chỉ đọc, không sửa cấu hình).  |
| `cloud-platform`     | Cả hai     | Xác thực với Cloud project (quota, billing của API).         |

<Note>
  Ngoài scope, còn cần **quyền tài khoản**: tài khoản Google đăng nhập phải có quyền trên tài khoản Ads (qua MCC) và quyền **Viewer** trở lên trên property GA4.
</Note>

### Mỗi MCP đọc được dữ liệu gì

<Columns cols={2}>
  <Card title="Google Ads MCP" icon="bullhorn">
    * **Cấu trúc tài khoản:** campaign, ad group, quảng cáo, keyword, asset, ngân sách, chiến lược giá thầu
    * **Chỉ số hiệu suất:** impressions, clicks, cost, conversions, giá trị chuyển đổi, CTR, CPC, ROAS
    * **Search terms:** cụm từ khách thực sự gõ, kèm keyword\_view
    * **Phân khúc:** theo ngày, thiết bị, mạng, vị trí địa lý, khung giờ, đối tượng
    * **Cây MCC:** liệt kê toàn bộ tài khoản con (customer\_client)
    * **Lịch sử thay đổi:** ai đổi gì, khi nào (change\_event)
  </Card>

  <Card title="Google Analytics MCP" icon="chart-line">
    * **Danh mục (Admin API):** account, property, cấu hình, custom dimensions/metrics, liên kết Google Ads
    * **Báo cáo linh hoạt:** ghép mọi dimension × metric qua run\_report
    * **Nguồn & chiến dịch:** source/medium, campaign, landing page, referrer
    * **Hành vi:** trang xem, sự kiện, engagement, thời lượng phiên
    * **Thương mại:** đơn hàng, doanh thu, sản phẩm, phễu mua hàng
    * **Realtime & đối tượng:** người đang online, thiết bị, khu vực, khách mới/quay lại
  </Card>
</Columns>

<Check>
  Cả 2 đều **chỉ đọc (read-only)**: không tạo, sửa, xóa campaign hay đổi cấu hình. An toàn để khám phá dữ liệu.
</Check>

### Đăng ký Developer Token (Basic access)

Token mới trong API Center mặc định ở mức **Test** (chỉ query test account). Để đọc tài khoản quảng cáo thật, phải xin duyệt **Basic access**. Google xét đơn thường trong 1–3 ngày.

1. Mở **API Center** trong tài khoản MCC.
2. Ở mục **Access level**, bấm **Apply for Basic access**.
3. Điền form theo file mẫu (đã soạn sẵn nội dung, chỉ sửa tên công ty/website).
4. Chờ email duyệt. Token không đổi, chỉ mức truy cập được nâng lên nên **không cần sửa config**.

### Lỗi thường gặp & cách sửa

<AccordionGroup>
  <Accordion title="invalid_grant — ADC hết hạn hoặc bị thu hồi">
    **Triệu chứng:** Query báo `invalid_grant: Token has been expired or revoked`. Đang chạy được rồi tự nhiên lỗi sau vài ngày.

    **Nguyên nhân:** App OAuth ở chế độ Testing nên credential ADC hết hạn sau khoảng 7 ngày.

    **Cách sửa:** Chạy lại lệnh đăng nhập ADC ở Bước 8 (giữ đủ 3 scope). Dứt điểm: Publish app OAuth sang Production ở Bước 3.
  </Accordion>

  <Accordion title="DEVELOPER_TOKEN_NOT_APPROVED — Token còn ở mức Test">
    **Triệu chứng:** Query tài khoản thật báo token chưa được duyệt, hoặc chỉ chạy được với test account.

    **Nguyên nhân:** Developer token mới mặc định ở mức Test.

    **Cách sửa:** Xin Basic access trong API Center (dùng file mẫu ở mục trên). Trong lúc chờ chỉ query được test account.
  </Accordion>

  <Accordion title="Server không hiện / session mới không thấy tool">
    **Triệu chứng:** Mục Local MCP servers trống, hoặc task Cowork mới không có tool của MCP.

    **Nguyên nhân:** Chưa khai vào `claude_desktop_config.json` (nơi session mới đọc), chưa khởi động lại, hoặc app tự ghi đè mất mcpServers.

    **Cách sửa:** Thêm server qua Edit Config rồi Cmd+Q khởi động lại ngay. Nếu bị xóa lại, thêm lại và restart liền trước khi app kịp ghi đè.
  </Accordion>

  <Accordion title="PERMISSION_DENIED — Không có quyền trên tài khoản">
    **Triệu chứng:** `USER_PERMISSION_DENIED` (Ads) hoặc lỗi 403 (GA4).

    **Nguyên nhân:** Tài khoản đăng nhập ADC không có quyền trên tài khoản Ads/property, hoặc sai Login Customer ID.

    **Cách sửa:** Đăng nhập đúng tài khoản có quyền. Kiểm tra Login Customer ID = ID của MCC (bỏ gạch nối). GA4 cần quyền Viewer trở lên.
  </Accordion>

  <Accordion title="SERVICE_DISABLED — API chưa được bật">
    **Triệu chứng:** `API has not been used in project ... or it is disabled`.

    **Nguyên nhân:** Chưa bật API tương ứng trong Google Cloud project.

    **Cách sửa:** Bật lại 3 API ở Bước 2 (Google Ads, Analytics Admin, Analytics Data).
  </Accordion>

  <Accordion title="Một MCP chạy, cái kia lỗi quyền">
    **Triệu chứng:** Ads OK nhưng GA4 báo thiếu quyền (hoặc ngược lại).

    **Nguyên nhân:** Lần đăng nhập ADC thiếu scope (chỉ có adwords hoặc chỉ có analytics).

    **Cách sửa:** Đăng nhập lại đủ cả 3 scope trong một lệnh (adwords + analytics.readonly + cloud-platform). Đừng đăng nhập riêng lẻ vì lần sau sẽ ghi đè lần trước.
  </Accordion>

  <Accordion title="Sai đường dẫn binary / server crash khi khởi động">
    **Triệu chứng:** Server báo lỗi khởi động, hoặc `command not found`.

    **Nguyên nhân:** Sai đường dẫn binary trong config, hoặc chưa cài venv.

    **Cách sửa:** Kiểm tra lại `command` trong config trỏ đúng binary, cài lại ở Bước 9 nếu cần.
  </Accordion>
</AccordionGroup>

<Accordion title="Prompt để Claude tự chẩn đoán" icon="stethoscope">
  ```text theme={null}
  MCP Google Ads (hoặc Analytics) đang báo lỗi khi tôi query. Chẩn đoán giúp:
  kiểm tra config, scope của ADC, API đã bật chưa, binary có chạy được không, rồi chỉ tôi cách sửa.
  ```
</Accordion>