Cách Setup Claude-Growth Kit 2026: Tool, API, MCP Cần Gì

Bạn vừa mua claude-growth kit. Giải nén xong, mở Claude Code lên… rồi đứng hình. Không biết bắt đầu từ đâu. Mình viết bài này để dắt bạn đi từng bước — từ con số 0 cho tới lúc chạy được lệnh audit đầu tiên. Không bỏ bước nào.

Cụ thể, bài này dẫn bạn qua 6 phase (làm từ trên xuống):

1. Cài tool local — Claude Code, Python, Git
2. Tải & cài kit
3. Lấy credential cho 4 MCP server — WordPress, DataForSEO, Gemini, Firecrawl
4. Nối Google — GSC + PageSpeed/CrUX + GA4 (đều miễn phí)
5. Wizard cấu hình từng site — tự tạo BRAND/VOICE/image-styles
6. Verify — 1 lệnh kiểm mọi thứ xanh là sẵn sàng chạy

Cái hay là bạn chỉ cần setup 1 lần. Sau đó dùng được cho cả 4 pipeline: audit website (/seo-pipeline), audit nội dung (/blog-audit-pipeline), viết bài (/blog-pipeline), và làm mới bài cũ (/blog-refresh-pipeline). Chúng xài chung một bộ tool + API — cài một lần, chạy được hết.

Muốn xem mỗi kit làm ra cái gì trước khi cài? Đọc 3 bài demo: audit website (/seo-pipeline), audit portfolio nội dung (/blog-audit-pipeline), và viết bài chuẩn SEO (/blog-pipeline).

Trước khi setup: bạn cần những gì, mỗi thứ để làm gì?

Đừng cài vội. Hiểu trước “mình đang lắp những mảnh nào” sẽ đỡ rối hơn nhiều.

Kit nối Claude Code với một số dịch vụ bên ngoài. Cách nối đó có tên là MCP (Model Context Protocol). Hình dung đơn giản: MCP giống mấy cổng USB trên máy tính. Mỗi cổng cắm vào một thiết bị khác nhau — WordPress, dữ liệu SEO, tạo ảnh, crawl web. Ngoài MCP còn vài API của Google (Search Console, PageSpeed, GA4) — tất cả đều miễn phí.

Bạn không cần đủ hết bảng dưới mới bắt đầu. Cài cái miễn phí trước. Thiếu cái nào, kit tự chạy nông hơn ở phần đó — không báo lỗi, không tắt máy. Khi cần sâu hơn thì gắn thêm tool trả phí.

Lưu ý quan trọng: Gemini chỉ cần cho kit viết bài (tạo ảnh). Nếu bạn chỉ mua kit để audit, bỏ qua Gemini cũng không sao — 2 pipeline audit không đụng tới nó.

Phase 1: Cần install local tools gì trước khi setup?

→ Cài 3 thứ chạy trên máy bạn (Claude Code, Python, Git). Xong là: máy sẵn sàng để cài kit.

Phase 1 cài 3 tool bắt buộc: Claude Code CLI, Python 3.10+, và Git. Không có 3 cái này, kit không chạy được. Có thêm 3 tool optional cho tính năng phụ. Verify từng tool sau khi cài trước khi sang bước tiếp theo.

Claude Code CLI (bắt buộc)

Đây là runtime chính cho toàn bộ kit. Cần tài khoản Claude Pro ($20/tháng) hoặc Max ($100-200/tháng) tại claude.ai. Sau khi có account:

npm i -g @anthropic-ai/claude-code
claude --version   # expect: 2.x

Nếu không muốn dùng npm, download installer trực tiếp từ trang Claude Code. Verify cho ra version 2.x trở lên.

Python 3.10+ (bắt buộc)

Scripts trong kit viết bằng Python. Cần 3.10 trở lên cho f-string + match/case syntax.

# Windows: tải từ python.org
# macOS: brew install python
# Linux: sudo apt install python3

python --version   # expect: Python 3.10+

Git (bắt buộc)

Kit dùng Git cho version tracking scripts. Tải tại git-scm.com (Windows), hoặc dùng package manager trên macOS/Linux.

git --version   # expect: git version 2.x

Tools optional

• Node.js 18+: bắt buộc nếu cài Claude Code qua npm (default install path ở trên). Cũng cần cho claude-gif-create (tạo GIF demo). Chỉ skip được nếu cài Claude Code qua direct installer + không cần GIF.
• ImageMagick: cần cho blog-chart WebP conversion. Skip nếu không dùng chart export.
• ffmpeg: cần cho GIF convert/edit. Skip nếu không làm video content.

Với T4 và T2, bạn không cần Node.js hay ImageMagick. Chỉ cài khi kit báo “dependency missing” ở tính năng bạn muốn dùng.

Phase 2: Download và install kit ra sao?

→ Tải kit về + chạy installer. Xong là: Claude Code đã có đủ skill của kit.

Phase này cài skills, agents, và scripts vào ~/.claude/ directory của máy. Nếu bạn đã mua kit qua Gumroad, link download ở trong email confirmation.

Download kit

Sau khi mua trên Gumroad, mở email confirmation để lấy download link. Hoặc download trực tiếp từ GitHub release: github.com/thenguyenvn90/claude-growth/releases/latest. File zip tên dạng claude-growth-vX.Y.Z.zip (X.Y.Z là version mới nhất, kích thước ~2.6MB).

Extract và cd vào project folder

unzip claude-growth-*.zip
# Tạo thư mục claude-growth-vX.Y.Z/ - đây IS project folder
cd claude-growth-*/

# Optional: đổi tên cho dễ nhớ
# mv claude-growth-* my-blog-project

Chạy installer

# macOS / Linux / Git Bash:
bash scripts/install.sh

# Windows PowerShell:
.\scripts\install.ps1

Expected output sau khi install xong: Skills 109, Agents 23, Scripts 12+, Version 1.0.x (x là minor version hiện tại). Nếu thấy số thấp hơn, xem phần Troubleshooting bên dưới.

Restart Claude Code

Phase 3: 4 MCP server bắt buộc — credential lấy ở đâu?

→ Lấy “chìa khóa” nối kit với WordPress + 3 dịch vụ ngoài. Xong là: kit đăng bài được + lấy được dữ liệu SEO.

MCP (Model Context Protocol) là cách Claude Code kết nối với external services. Kit dùng 4 MCP server: wp-mcp-ultimate (WordPress), dataforseo-mcp (SEO data), nanobanana-mcp (image generation), và firecrawl-mcp (web crawling). 4 cái này là bắt buộc. (Chrome DevTools MCP là server thứ 5 — tùy chọn, đã nói ở mục “Trước khi setup”; không tính vào 4 cái bắt buộc.) Bạn cần credentials cho từng cái trước khi fill .mcp.json.

WordPress Application Password (free)

Đây là credential kết nối kit với WordPress site của bạn. Không phải login password thông thường.

1. Vào WP Admin, trỏ đến Users > Profile
2. Scroll xuống cuối trang, tìm section Application Passwords
3. Điền tên “claude-growth”, click Add New Application Password
4. Copy password ngay (format 24 ký tự: abcd 1234 efgh 5678 ijkl 9012). Password chỉ hiện 1 lần.

Save email WordPress admin + application password vào notepad tạm để fill .mcp.json sau.

Cần role gì + dùng làm gì? Tạo Application Password từ một user có role Editor trở lên. Với /blog-pipeline và /blog-refresh-pipeline, app-password này cho phép kit: (1) đọc các bài đã đăng trên site — để chống trùng lặp keyword (anti-cannibalization) và chọn bài cần refresh; và (2) viết — tạo draft, upload ảnh, set featured image, điền Rank Math meta, schedule. Editor đủ quyền edit_posts / publish_posts cho cả hai. KHÔNG cần quyền Admin cho việc đọc + viết bài.

App-password này dùng để kết nối kit ↔ WordPress — khai qua MCP wp-mcp-ultimate trong .mcp.json, hoặc wp_credentials trong BRAND.md. Cách kết nối chi tiết (các phương án MCP, lấy app-password, phân quyền) xem bài Claude Code + WordPress qua MCP.

Khi nào mới cần Admin? Chỉ khi muốn audit backend sâu mà WordPress giới hạn cho admin (vd liệt kê plugin/theme đã cài) — tùy chọn, không liên quan tới đọc/viết bài. Ngoài ra một số setup RankMath cần quyền cao hơn để update meta qua REST; gặp 401/403 khi set focus keyword thì dùng app-password role Admin cho riêng site đó.

DataForSEO API password (~$50 deposit tối thiểu)

DataForSEO cung cấp SERP data, competitor + cluster data, và on-page checks cho T2+ tier. Backlink profile cơ bản kit lấy free qua Moz/Common Crawl; chỉ index backlink lớn + link velocity của DataForSEO Backlinks API mới cần $100/tháng commitment (xem DataForSEO pricing). Pay-as-you-go, không subscription. Nếu chưa quen với DataForSEO, xem bài DataForSEO Free Trial 2026: $1 Sandbox Trong 30 Phút để test nhẹ trước khi deposit $50 thật.

1. Sign up tại app.dataforseo.com
2. Deposit tối thiểu $50 (đủ cho ~150-250 audit cycle theo estimate thực tế)
3. Vào Account > API Access, copy API Password

Gemini API key cho Nano Banana (~$0.04/ảnh, có quota test free)

nanobanana-mcp dùng Gemini API để generate ảnh cho bài viết. AI Studio có quota test miễn phí để thử trước; bản trả phí chỉ khoảng $0.04/ảnh (rất rẻ).

1. Sign up hoặc đăng nhập tại aistudio.google.com (dùng Google account)
2. Click Get API key
3. Copy key. Format: AIzaSy... (39 ký tự)

Firecrawl API key

Firecrawl dùng để crawl và extract HTML từ site. Kit dùng cho on-page analysis và competitor scraping.

1. Sign up tại firecrawl.dev
2. Vào Dashboard, click API Keys
3. Copy key. Format: fc-... (40 ký tự)

Firecrawl cho miễn phí 1.000 trang/tháng — đủ cho hầu hết site nhỏ. Cần nhiều hơn thì gói Hobby $16/tháng (trả năm) = 5.000 trang.

Fill .mcp.json

Sau khi có đủ 4 credentials, fill vào file config:

cp .mcp.json.template .mcp.json
# Mở .mcp.json bằng editor

Cấu trúc .mcp.json nhìn gần giống như sau (replace 4 placeholder block <...> với credentials thật):

{
  "mcpServers": {
    "wp-mcp-ultimate": {
      "command": "node",
      "args": ["/absolute/path/to/wp-mcp-ultimate/dist/index.js"],
      "env": {
        "WORDPRESS_URL": "<https://yoursite.com>",
        "WORDPRESS_USER": "<wp-admin-username>",
        "WORDPRESS_PASSWORD": "<24-char-app-password>"
      }
    },
    "dataforseo-mcp": {
      "command": "npx",
      "args": ["-y", "dataforseo-mcp-server"],
      "env": {
        "DATAFORSEO_LOGIN": "<your-email>",
        "DATAFORSEO_PASSWORD": "<dataforseo-api-password>"
      }
    },
    "nanobanana-mcp": {
      "command": "npx",
      "args": ["-y", "nanobanana-mcp"],
      "env": {"GOOGLE_AI_API_KEY": "<AIzaSy_your_key>"}
    },
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {"FIRECRAWL_API_KEY": "<fc-your-key>"}
    }
  }
}

Sau khi save .mcp.json, restart Claude Code một lần nữa để MCP servers load credentials mới. Verify bằng lệnh:

python scripts/verify_setup.py --site yoursite.com
# Expected ở mốc này:
#   ✓ WP REST 200  ✓ DataForSEO 20000 OK  ✓ Gemini 200  ✓ Firecrawl
#   ⚠ BRAND.md missing fields  ⚠ image styles missing  ⚠ GSC OAuth (chưa setup)
# Tổng ~3 warning là bình thường, sẽ về 0 sau Phase 4-6.

Ở giai đoạn này, verify show ~3 warning là expected (BRAND.md chưa derive xong, image styles chưa generate, GSC OAuth chưa setup ở Phase 4). Critical phải là 0, các MCP server phải ✓. Sau Phase 4 (GSC) + Phase 5 (wizard), warning về 0. Xem chi tiết output mẫu ở Phase 6 bên dưới.

Phase 4: Kết nối Google (GSC + PageSpeed + GA4) chi tiết

→ Nối kit với dữ liệu thật của Google (thứ hạng, tốc độ, traffic). Xong là: report có data thật + panel SEO-ROI.

Đây là phần mở khóa dữ liệu thật từ Google — thứ làm report của kit khác hẳn tool đoán mò. Ba kết nối, đều miễn phí: Search Console (thứ hạng + lượt click thật theo từ khóa), PageSpeed/CrUX (tốc độ trang người dùng thật cảm nhận), và GA4 (traffic + chuyển đổi — thứ mở ra panel SEO-ROI trong report). Làm tuần tự từ trên xuống.

Trước hết — xác định bạn thuộc case nào. Kit chỉ ĐỌC dữ liệu (không ghi gì lên site). Nên dù bạn là owner hay chỉ được chia sẻ quyền xem (read), setup gần như y hệt — khác biệt chính:

Agency/consultant audit site của khách thường rơi vào case “chỉ được share quyền xem” — vẫn audit đủ. Giờ làm tuần tự bên dưới.

GSC OAuth — lấy dữ liệu Search Console

Dữ liệu GSC thật — clicks, impressions, vị trí theo từng query — được xác thực qua script google_auth.py của skill blog-google. Credential lưu tại ~/.config/claude-seo/. Kit không dùng tool ngoài.

Để kết nối, mình dùng cơ chế đăng nhập bằng tài khoản Google cá nhân của mình — gọi là OAuth. Với một site solo, đây là cách đơn giản nhất: không cần tạo Service Account, không cần chỉnh quyền trong GSC, chỉ 1 lệnh và 1 popup trình duyệt là xong. Sau khi setup, xem bài Claude Code Search Console: Chạy GSC Trong 3 Phút để hiểu kit query GSC data ra sao trong pipeline.

Bật API trên Google Cloud

• Vào Google Cloud Console, tạo project mới.
• APIs & Services, Library: bật Google Search Console API, PageSpeed Insights API, Chrome UX Report API, và Google Analytics Data API (cho GA4 — mở panel SEO-ROI trong report).

Tạo OAuth client + chạy lệnh xác thực

1. Vào Cloud Console, tạo credentials.
   Mở APIs & Services → Credentials, bấm Create credentials → OAuth client ID.
2. Chọn Application type: Desktop app.
   Script chạy trên máy local — không phải webapp. Bỏ qua các option Web application / Android / iOS.
3. Download file client_secret.json về máy.
4. Tạo folder config (nếu chưa có).
   Mở terminal, chạy:

   mkdir -p ~/.config/claude-seo

5. Đặt file client_secret.json vào đúng chỗ.
   Di chuyển file vừa download vào:

   ~/.config/claude-seo/client_secret.json

   Token sẽ được generate vào cùng folder này sau bước tiếp theo.

6. Chạy lệnh xác thực.
   Lệnh này sẽ mở một tab trình duyệt để bạn đăng nhập:

   python ~/.claude/skills/blog-google/scripts/google_auth.py --auth --creds ~/.config/claude-seo/client_secret.json

7. Đăng nhập Google account đã verify GSC property → grant permissions.
   Trình duyệt popup — chọn đúng account có GSC, bấm cho phép.
8. Xong. Token tự lưu vào:

   ~/.config/claude-seo/oauth-token.json

   Không cần làm thêm gì. Từ đây script dùng token này để kết nối GSC.

Verify

python ~/.claude/skills/blog-google/scripts/google_auth.py --check gsc
# Expected: siteOwner / siteFullUser / siteRestrictedUser (cả 3 đều đọc được data)

Xem hướng dẫn canonical bằng python ~/.claude/skills/blog-google/scripts/google_auth.py --setup.

Alternative: Service Account (chỉ khi cần)

Service Account JSON dùng cho 2 use case: (1) multi-site cùng một service email, hoặc (2) Google Workspace với domain-wide delegation. Cho 1 site solo, OAuth ở trên gọn hơn. Nếu vẫn muốn dùng Service Account:

• IAM & Admin, Service Accounts, Create Service Account.
• Tạo key dạng JSON, tải về và lưu an toàn (ví dụ ~/.config/claude-seo/service-account.json).
• Search Console, Settings, Users and permissions, Add user: dán client_email của service account (dạng ...@...iam.gserviceaccount.com), set quyền Restricted (đủ read, an toàn hơn Full).

Lấy API key cho PageSpeed + CrUX

PageSpeed Insights và CrUX (CWV field data, 25-week trend) chỉ cần API key, không cần service account, và lưu chung trong ~/.config/claude-seo/google-api.json. Thiếu key này thì audit vẫn chạy, chỉ thiếu PSI lab data và CrUX history (tùy chọn nâng cao).

Tạo API key

• APIs & Services, Credentials, Create credentials, API key. Sau khi tạo, copy key (format AIzaSy...) và lưu tạm vào notepad.
• Click vào key vừa tạo để mở settings. Tìm section API restrictions (KHÔNG phải Application restrictions). Chọn Restrict key, tick 2 API: PageSpeed Insights API và Chrome UX Report API. Click Save.

Thêm vào google-api.json (chọn 1 variant)

Tùy theo Phase 4 bạn chọn OAuth hay Service Account, file ~/.config/claude-seo/google-api.json sẽ khác nhau. Chỉ paste 1 trong 2 variant dưới, KHÔNG paste cả hai (sẽ conflict auth path).

Variant A: OAuth (recommended cho 1 site), OAuth token đã save ở Phase 4, file này chỉ cần api_key + gsc_property:

{
  "api_key": "AIzaSy_YOUR_KEY",
  "gsc_property": "sc-domain:yoursite.com"
}

Variant B: Service Account (multi-site / Workspace), thay OAuth bằng service account JSON path:

{
  "api_key": "AIzaSy_YOUR_KEY",
  "service_account_path": "~/.config/claude-seo/service-account.json",
  "gsc_property": "sc-domain:yoursite.com"
}

Verify toàn bộ Google credential: python ~/.claude/skills/blog-google/scripts/google_auth.py --check.

GA4 — mở panel organic traffic + SEO-ROI (nên bật)

GSC đủ cho audit cốt lõi rồi. Nhưng GSC chỉ cho bạn biết trang nào được tìm thấy — không biết trang đó có giữ chân người dùng hay không. GA4 lấp chỗ trống đó: bạn thấy được organic traffic thật của từng landing page, rồi so với chuyển đổi — đây là phần làm report gắn được với doanh thu.

Ví dụ: bạn có trang “tour Đà Lạt 4N3Đ” xếp hạng #3 trên GSC, nhưng GA4 cho thấy bounce rate 90% — khách vào rồi thoát ngay. Không có GA4, bạn tưởng trang này “ổn”. Có GA4, bạn biết phải sửa ngay.

Không bật GA4 thì pipeline vẫn chạy bình thường — chỉ thiếu cột organic-traffic trong report. Muốn bật thì làm 5 bước:

1. Lấy GA4 Property ID
   Property ID là dãy số định danh tài sản GA4 của bạn (giống “số chứng minh thư” cho website trong Google Analytics). Vào GA4 Admin → Property Settings → copy trường Property ID (vd 123456789). Khi điền vào config thì viết dạng properties/123456789.
2. Bật Google Analytics Data API
   Vào Google Cloud Console — dùng cùng project đã tạo OAuth ở Phase 4. Chọn APIs & Services → Enable APIs → tìm và bật Google Analytics Data API.
3. Cấp quyền cho tài khoản truy cập GA4 (bước hay quên nhất)
   Có 2 cách tùy bạn dùng auth nào:
   • Dùng OAuth: google_auth.py phiên bản hiện tại (≥ 2026-06) đã xin sẵn cả 3 scope trong 1 lần --auth (GSC webmasters + GA4 analytics.readonly + Indexing) — nên thường không cần re-auth. Chỉ re-auth nếu token cũ thiếu analytics.readonly. Ngoài ra, email Google của bạn phải là Viewer trên GA4 property: vào GA4 Admin → Property Access Management → Add → chọn role Viewer.
   • Dùng Service Account: thêm client_email của service account vào GA4 Admin → Property Access Management → role Viewer.
4. Thêm Property ID vào file config
   Mở ~/.config/claude-seo/google-api.json, thêm dòng:
   "ga4_property_id": "properties/123456789"
5. Verify — kiểm tra kết nối
   Chạy lệnh:
   python scripts/verify_setup.py --site <domain>
   Dòng GA4 phải báo: properties/... authorized (Data API metadata 200 OK)
   Nếu thấy lỗi:
   • 403 = thiếu scope analytics.readonly hoặc email chưa được thêm làm Viewer
   • 404 = sai Property ID — kiểm tra lại bước 1

Lưu ý thêm: verify script cũng kiểm PSI/CrUX api_key (dữ liệu CWV field thật từ người dùng thực) — cùng file google-api.json, field api_key. Nếu chưa có key này thì CWV trong report là lab data, không phải field data.

Phase 5: Cấu hình từng site bằng wizard

→ Wizard quét site của bạn rồi tự tạo 3 file “persona” (BRAND / VOICE / image-styles) cho từng site. Xong là: kit viết & audit đúng giọng văn + thương hiệu của site đó.

Đây là phase tốn thời gian nhất nhưng cũng quan trọng nhất. Wizard /claude-growth-onboarding scrape site của bạn, tự derive brand color, giọng văn, audience type, image style preference, rồi save vào 3 file: sites/yoursite.com/BRAND.md, VOICE.md, và image-styles.md. Ba file này là “persona” mà mọi agent trong kit đọc khi chạy pipeline, ví dụ bài Claude Blog: Viết Bài Tự Động 30 Phút giải thích BRAND + VOICE được skill blog-write tiêu thụ thế nào.

4 scenario wizard hỗ trợ

Scenario A: site đã có production (most common)

/claude-growth-onboarding

Wizard sẽ hỏi URL site, rồi tự scrape. Sau khi scrape xong, wizard hiện kết quả derive cho từng dimension: ngôn ngữ, brand color, audience type, tone 4D. Bạn review và confirm từng field. Step confirm-loop này khá interactive, tuy nhiên defaults thường đúng 80-90% cho site có content đa dạng.

Wizard save output vào:

• sites/yoursite.com/BRAND.md (màu, logo, URL cấu hình)
• sites/yoursite.com/VOICE.md (giọng văn, audience, tone)
• sites/yoursite.com/image-styles.md (style ảnh preferred)

Khi chạy wizard, bạn sẽ thấy gì?

Wizard hỏi bạn từng câu một, mỗi câu có sẵn lựa chọn để bấm — bạn không phải tự gõ giá trị. Đại khái:

Gõ back bất cứ lúc nào để quay lại câu trước. Defaults wizard đoán thường đúng ~80-90% cho site có content đa dạng — phần lớn bạn chỉ bấm OK.

Wizard “đoán” giọng văn của bạn bằng cách nào?

Không phải AI đoán mò — nó đo từ chính nội dung site bạn. Wizard quét text rồi đếm tín hiệu thật để chấm điểm 4 trục giọng (chuẩn NN/g):

• Trang trọng ↔ Thân mật: đếm đại từ — “bạn, mình, tớ” (thân mật) so với “quý khách, anh/chị, chúng tôi” (trang trọng). Site bạn dùng “mình/bạn” nhiều → nó chấm thân mật cao.
• Hài ↔ Nghiêm · Nhiệt tình ↔ Khách quan · Tôn trọng ↔ Bốc đồng: đếm tần suất từ hài / từ hype / từ quan điểm + dấu “!” trên mỗi 1000 chữ.

Màu thương hiệu thì lấy từ logo thật (đọc pixel); định vị thì trích câu “Chúng tôi là…” trên trang /about. Site nào nội dung mỏng (<500 chữ) thì wizard tự báo “chưa chắc — bạn duyệt kỹ”. Vì đo từ chữ thật của bạn nên defaults đúng ~80-90%; chỗ nào lệch bạn chỉnh ngay ở bước confirm.

python ~/.claude/scripts/welcome/derive_brand.py --url https://yoursite.com --corpus --out ./voice-profile

Chạy xong, 3 file “persona” nằm ở đâu?

Wizard lưu vào thư mục sites/[tên-site]/ ngay trong project của bạn:

sites/yoursite.com/
├── BRAND.md          ← thương hiệu, màu, audience, định vị
├── VOICE.md          ← giọng văn 4 trục + tâm lý tìm kiếm
└── image-styles.md   ← style ảnh hero

Đây là 3 file mà mọi pipeline đọc khi chạy (để viết/audit đúng giọng + thương hiệu site đó). Muốn chỉnh tay sau này — đổi giọng, sửa màu — cứ mở thẳng sites/yoursite.com/BRAND.md bằng editor, sửa, lưu. Không cần chạy lại wizard.

Verify per-site config

python scripts/verify_setup.py --site yoursite.com
# Expected:
# ✓ BRAND.md parsed (language + wp_url present)
# ✓ VOICE.md loaded
# ✓ image styles configured

Scale lên nhiều site cùng lúc (agency mode)

Nếu setup cho nhiều site (agency, multi-brand), Phase 5 là phần tốn time nhất per-site và scale tuyến tính theo N site. Workflow batch:

# Tạo sites.txt liệt kê domain (1 site/dòng)
cat > sites.txt <<EOF
site1.com
site2.com
site3.com
EOF

# Batch onboarding với --auto-derive flag (skip confirm-loop manual)
for site in $(cat sites.txt); do
  python scripts/init_project.py --site "$site" --auto-derive
done

# Batch verify
for site in $(cat sites.txt); do
  python scripts/verify_setup.py --site "$site" --no-probe
done

--auto-derive dùng default cho mọi field (brand color, voice, image style) và skip confirm-loop. Phù hợp khi bạn tin defaults hoặc sẽ refine sau qua manual edit sites/[site]/BRAND.md. Cho agency 20+ client site, batch mode rút workflow từ nhiều giờ manual xuống còn 1 lệnh.

Phase 6: Verify toàn bộ setup (1 lệnh)

→ Chạy 1 lệnh kiểm 14 mục. Xong là: thấy 14/14 xanh = sẵn sàng chạy cả 4 pipeline.

Phase cuối cùng là một lần chạy verify_setup.py để confirm toàn bộ stack hoạt động. Script check 14 hạng mục và báo cáo theo format pass/warn/fail. Mục tiêu: 0 critical, 0 warning.

Chạy verify tổng hợp

python scripts/verify_setup.py --site yoursite.com

Script check 14 hạng mục: BRAND.md, VOICE.md, image styles, .mcp.json, WP REST authentication, DataForSEO authentication, Banana (Gemini) MCP, Gemini API, Firecrawl API, GSC OAuth token, PSI/CrUX api_key, GA4 Data API (cả hai từ Phase 4), Chrome DevTools, và workflow-tracker.

Manual checks bổ sung

Một số check mà verify_setup.py không cover được hoàn toàn:

claude --version           # 2.x
python --version           # 3.10+
ls ~/.claude/skills | wc -l  # should be 100+
python ~/.claude/skills/blog-google/scripts/google_auth.py --check gsc  # siteOwner

Output mẫu qua 2 mốc setup

Khi mọi phase đã xong, chạy verify lần cuối phải ra 0 critical, 0 warning — như dưới đây. Đây là trạng thái “mọi thứ xanh”, sẵn sàng chạy pipeline:

$ python scripts/verify_setup.py --site yoursite.com

claude-growth health check on yoursite.com
=========================================
✓ BRAND.md         parsed OK, language=vi, wp_url=https://yoursite.com
✓ VOICE.md         found
✓ image styles     found
✓ .mcp.json        WP endpoint host matches BRAND (yoursite.com)
✓ WP REST          authenticated 200 OK
✓ DataForSEO       your@email.com authenticated, 20000 OK (free user_data probe, $0)
✓ Banana MCP       nanobanana-mcp server present
✓ Gemini API       AIzaSy*** authenticated, 200 OK
✓ Firecrawl        firecrawl-mcp + FIRECRAWL_API_KEY present
✓ Chrome DevTools  not configured — optional (CrUX/PSI cover field CWV)
✓ GSC OAuth        authorized: sc-domain:yoursite.com (siteOwner)
✓ PSI/CrUX         api_key AIzaSy*** authorized (CrUX API reachable)
✓ GA4              properties/123456789 authorized (Data API metadata 200 OK)
✓ workflow-tracker present

Summary: 0 critical, 0 warning. (DataForSEO probe used free user_data endpoint, $0.)
All critical checks pass. Pipelines will run (warnings = optional/degraded coverage).

0 critical, 0 warning là hoàn hảo. GSC OAuth tự nhận property authorization. Nếu bạn vẫn thấy warning về GSC, chạy python ~/.claude/skills/blog-google/scripts/google_auth.py --check gsc để confirm tay — output siteOwner là OK.

Flag --no-probe bỏ qua live API check (WP REST, DataForSEO, Gemini auth) để run nhanh hơn, mature state với flag này show 1 warning (WP REST skipped là intentional). Dùng khi muốn quick check status mà không spend API quota, ví dụ sau khi edit .mcp.json chỉ cần verify config presence.

Khi nào “Warning” là chấp nhận được?

Mature setup giờ achievable 0 warning hoàn toàn. Nếu vẫn còn warning, phân loại theo 2 nhóm dưới đây.

Sau khi setup: chạy gì, report nằm ở đâu, có gì trong đó?

Verify xanh hết rồi thì bạn đã sẵn sàng. Tùy mua kit nào, gõ 1 trong 3 lệnh:

# Audit toàn bộ website (technical SEO + GEO)
/seo-pipeline yoursite.com

# Audit portfolio nội dung (chấm điểm + xếp hàng bài cần refresh)
/blog-audit-pipeline yoursite.com

# Viết 1 bài chuẩn SEO từ keyword
/blog-pipeline "your keyword"

Lần đầu nên chạy thử nhanh: thêm cờ --fast vào lệnh audit (vd /seo-pipeline yoursite.com --fast) để xem preview ~30 phút thay vì bản đầy đủ ~90–120 phút.

Report nằm ở đâu?

Mỗi lần chạy, kit tạo một thư mục riêng cho lần audit đó theo công thức audits/[tên-site]/[ngày]_seo-pipeline/. Chạy lại ngày khác → thư mục mới, không đè bản cũ. Nên bạn luôn có lịch sử để so “tháng này khá hơn tháng trước chưa”.

Nhìn vào thư mục thấy hơn chục file dễ ngợp, nhưng thật ra bạn chỉ cần mở 1 file:

Mẹo nhớ: số nhỏ = bước sớm, số lớn = gần ra report (phase6 điểm sinh sau phase1 quét).

Report trông như thế nào?

Đây là report thật kit chạy cho ongboit.com. Bạn mở xem bản đầy đủ tương tác ở đây: report audit website và report audit nội dung.

3 việc nên làm tiếp

1. Đọc kỹ report đầu tiên — bắt đầu từ mục “3 việc cần sửa trước”, rồi tới các lỗi P0/P1.
2. Xem bức tranh toàn cảnh: checklist các yếu tố audit website 2026 giải thích kit check những gì và vì sao mỗi cái quan trọng.
3. Đặt lịch audit định kỳ: dùng cron/GitHub Actions chạy /seo-pipeline hằng tháng, thêm cờ --baseline để so với lần trước, phát hiện trượt sớm.

Troubleshooting: Lỗi hay gặp và cách fix?

Phần lớn lỗi setup rơi vào các nhóm dưới đây. Kiểm tra từ trên xuống theo thứ tự xảy ra lỗi.

install.sh báo “skills/claude-blog/skills/ not found”

Đây là kit cũ trước khi folder structure refactor. Fix: download version mới nhất từ GitHub releases (link trong Gumroad email) hoặc mở lại email Gumroad để lấy download link mới (lifetime updates tự động). Re-run install.sh.

.mcp.json credentials không xác thực được

Nguyên nhân gần như chắc chắn là dùng login password của DataForSEO thay vì API password. Vào Account > API Access trên dashboard DataForSEO để lấy đúng API password. Hai cái khác nhau hoàn toàn.

GSC property “could not confirm” warning

Chạy python ~/.claude/skills/blog-google/scripts/google_auth.py --check gsc để check manual. Nếu site xuất hiện với siteOwner, warning là false alarm của auto-detect. Nếu site không xuất hiện, verify property trong Search Console với cùng Google account đã dùng khi chạy google_auth.py --auth.

Chạy --auth báo “localhost refused to connect” / không lưu token

google_auth.py --auth mở một server tạm ở localhost:8085 để bắt code sau khi bạn grant. Nếu trình duyệt báo “localhost refused to connect” (thường do port 8085 bị chiếm hoặc firewall chặn), đừng lo: copy nguyên URL trên thanh địa chỉ (đoạn có ?code=...), rồi chạy lệnh terminal mà script đã in ra: python ~/.claude/skills/blog-google/scripts/google_auth.py --exchange --creds ~/.config/claude-seo/client_secret.json --code 'DÁN_CODE_VÀO_ĐÂY'. Token sẽ lưu như bình thường.

PSI API báo “quota exceeded”

Free tier của Google Cloud PSI API có giới hạn 25,000 queries/ngày, rất khó hit trừ khi audit hàng nghìn URL trong ngày. Nếu hit limit, kit tự fallback về public PSI endpoint. Không ảnh hưởng đến kết quả audit thông thường.

Wizard không hỏi gì sau khi chạy /claude-growth-onboarding

Skills chỉ load tại session start. Nếu mở Claude Code trước khi chạy install.sh, session đó không có skills mới. Đóng và mở lại Claude Code. Chạy /help để verify skills list hiện ra trước khi thử lại wizard.

GA4 báo lỗi 403 khi verify

Dòng GA4 trong verify_setup.py báo 403 nghĩa là token thiếu scope analytics.readonly, HOẶC email Google của bạn chưa được thêm làm Viewer trên GA4 property. Fix: vào GA4 Admin → Property Access Management → Add → chọn role Viewer cho đúng email. Nếu báo 404 thì sai Property ID (kiểm lại ga4_property_id trong google-api.json).

/seo-pipeline hoặc /blog-pipeline báo “no MCP”

MCP servers load khi Claude Code start và đọc .mcp.json. Nếu bạn edit .mcp.json sau khi đã mở session, cần restart Claude Code. Lỗi này thường xuất hiện ngay sau bước fill credentials Phase 3.

Câu Hỏi Thường Gặp

API key có expire không?

Không. Google Cloud API key không expire trừ khi bạn xoá project. GSC OAuth refresh token valid vô thời hạn. DataForSEO API password là permanent. Firecrawl API key cũng permanent. Gemini API key valid cho đến khi Google Cloud project bị xoá. Bạn chỉ cần setup credentials 1 lần cho máy.

Setup 1 lần dùng cho nhiều site được không?

Có — nhưng một phần. Phase 1 (cài tool local), Phase 4 (GSC OAuth), và các API key của Phase 3 (DataForSEO/Gemini/Firecrawl) chỉ cài 1 lần cho máy, dùng chung mọi site. Riêng WordPress App Password (cũng nằm trong Phase 3) thì mỗi site một cái khác. Phase 2 (cài kit) và Phase 5 (wizard) làm lại mỗi site. Nên site thứ hai chủ yếu chỉ cần Phase 2 + Phase 5 + một WP password mới.

Mình audit site của khách (không phải owner) được không?

Được. Kit chỉ đọc dữ liệu nên quyền view/read là đủ — owner chỉ cần chia sẻ quyền xem GSC (Add user, quyền Restricted) + GA4 (role Viewer) cho email của bạn. Chi tiết ở bảng đầu Phase 4. Chỉ 2 tính năng ghi (submit Indexing API + nộp sitemap) cần quyền owner, nhưng phần audit thì đầy đủ. Agency/consultant thường dùng cách này.

Update kit ra sao khi có version mới?

Mở Gumroad email để nhận thông báo version mới (lifetime updates). Download zip mới, unzip vào folder, chạy lại install.sh (hoặc install.ps1 trên Windows). Installer là idempotent: override skills, agents, scripts nhưng giữ nguyên .mcp.json, per-site config trong sites/, và folder audits/. Không mất data cũ.

Site không phải WordPress có dùng được không?

Có. WP MCP là optional. /seo-pipeline parse HTML trực tiếp từ bất kỳ site nào: Shopify, Webflow, Hugo, Astro, Next.js, static HTML. Chỉ thiếu một tính năng: autofix push tự động vào WordPress. Tất cả phần audit report, gợi ý fix, và content pipeline vẫn chạy bình thường với non-WP site.

T4 chạy được /seo-pipeline không?

Có. Pipeline tự detect tier dựa trên credentials có trong .mcp.json. Ở T4 mode, kit bỏ qua 6 heavy agent cần API trả phí (DataForSEO/Firecrawl) — giống khi chạy --fast. Report vẫn sinh ra nhưng có section coverage_gaps liệt kê check nào bị bỏ qua. Đủ để học và hiểu kit trước khi deposit thêm.

DataForSEO cost mỗi audit thực tế bao nhiêu?

Audit 1 site lần đầu: ~$0.10-0.30 (SERP lookups + on-page checks). Audit content portfolio 100 bài: ~$3-5. $50 deposit tối thiểu đủ cover ~150-250 audit cycle. Nếu dùng kit regular, deposit $30 mỗi tháng là comfortable cho T2 workflow thông thường.

Tóm lại

Setup claude-growth lần đầu là 6 phase, làm từ trên xuống. Phần lâu nhất là lấy credential (~30–60 phút) — nhưng chỉ làm 1 lần cho máy. Site thứ hai về sau chỉ cần Phase 2 (cài kit) + Phase 5 (wizard) + một WordPress App Password mới.

Sau khi verify_setup.py báo 14/14 xanh, bạn có đủ stack để chạy cả 4 pipeline với dữ liệu thật từ Google (thứ hạng, tốc độ, traffic + SEO-ROI) — thứ làm report khác hẳn tool đoán mò.

Giờ bắt đầu: quay lên Phase 1 và làm tuần tự. Gặp lỗi thì xuống mục Troubleshooting. Setup xong, chạy lệnh audit đầu tiên — /seo-pipeline yoursite.com --fast — để xem report preview trong ~30 phút.