Cắm Google Search Console vào Claude Code qua MCP server

#fullstack #ai #webdev #javascript

Originally published on NextFuture

Bạn mở Search Console, export CSV, dán vào spreadsheet, rồi quay lại editor để đoán page nào đang tụt CTR. Vòng đó lặp mỗi tuần và kết thúc bằng cảm tính.

Cách ngắn hơn: cắm Search Console thẳng vào Claude Code qua MCP, để agent đọc số và sửa đúng page trong một session. Dưới đây là setup, ba bẫy, và prompt dùng ngay.

Kiến trúc: đây là bài toán tầng tool

Chuỗi kết nối có bốn mắt: Claude Code → MCP over stdio → mcp-gsc chạy local → OAuth 2.0 → Search Console API. Server là mcp-gsc, dự án open-source của Amin Forou; nó chuyển tác vụ Search Console thành tool Claude gọi được: performance analysis, URL inspection, sitemap management, period comparisons, property discovery.

MCP đúng vai ở đây: theo phân tích của NeuralCoreTech, MCP là lớp nối agent với "tools, resources, files, databases and APIs", còn A2A mới là lớp nối các agent độc lập. Không cần multi-agent để đọc GSC — chỉ cần một protocol layer chuẩn thay cho custom integration từng service.

Setup bốn bước

Google Cloud: tạo project riêng, enable Google Search Console API. Sang Google Auth Platform: khai app name + support email (Branding), audience External, giữ app ở Testing, thêm account của bạn vào Test users — account đó phải đã có quyền trên property.
OAuth client: tạo client loại Desktop app, tải JSON về chỗ private cố định (~/Documents/credentials/gsc-client-secrets.json). Không commit file này.
Cài server: gọn nhất là uvx (chạy package trong môi trường Python tách biệt). Cài uv, rồi giữ lại đường dẫn đầy đủ từ which uvx.
Nối vào Claude Code bằng đường dẫn tuyệt đối:

claude mcp add-json --scope user gscServer '{
  "type": "stdio",
  "command": "/Users/yourname/.local/bin/uvx",
  "args": ["mcp-search-console"],
  "env": { "GSC_OAUTH_CLIENT_SECRETS_FILE": "/Users/yourname/Documents/credentials/gsc-client-secrets.json" }
}'

Kiểm tra bằng claude mcp list và claude mcp get gscServer. --scope user để integration có ở mọi project local mà không commit đường dẫn credential vào repo. Cài tay từ repository thay vì uvx thì cần Python 3.11 trở lên.

Ba lỗi mất thời gian nhất

Hết hạn sau bảy ngày. Với external app còn ở Testing, Google thường hết hạn authorization và refresh token sau bảy ngày. Auth đứt đột ngột thì gọi tool reauthenticate và approve lại — bài gốc chỉ đưa đúng cách chữa này, nên coi nhịp bảy ngày là chi phí cố định của setup Testing.
spawn uvx ENOENT. Claude Code có thể không thừa hưởng PATH của terminal, nên khai uvx trần sẽ lỗi. Dùng full path.
Property trả 404. Có hai format: sc-domain:example.com và URL-prefix https://www.example.com/. Với URL-prefix, protocol, hostname và dấu / cuối phải khớp chính xác — chạy list_properties rồi copy đúng giá trị API trả về.

Prompt đáng chạy ngay

Server expose các tool như get_performance_overview, compare_search_periods, inspect_url_enhanced, check_indexing_issues. Hai prompt cho ra việc-để-làm:

Find pages ranking in positions 1 to 10 with at least 1,000 impressions
and CTR below 2%. Show their leading queries and suggest accurate title improvements.

For sc-domain:example.com, find non-branded queries with at least 500 impressions
and positions from 11 to 20 in the last 28 days. Group them by ranking page and
recommend whether to update an existing page or create a new one.

Freshness: giữ default GSC_DATA_STATE=all cho số kiểu dashboard mới nhất; đổi sang GSC_DATA_STATE=final khi cần số ổn định để báo cáo, đánh đổi là trễ một nhịp.

Chốt an toàn trước khi bật

Scope server xin là https://www.googleapis.com/auth/webmasters — read/write, không phải read-only. Operation destructive của mcp-gsc vẫn tắt cho tới khi set GSC_ALLOW_DESTRUCTIVE=true: để nguyên. Giữ client JSON và OAuth token cache ngoài repo, review từng MCP tool call trước khi approve, revoke OAuth app nếu credential bị lộ.

Tác giả bài gốc nhận định giá trị lớn nhất không phải sản xuất thêm content SEO, mà là đưa dữ liệu search thật vào tay coding assistant để nó điều tra đúng page trước khi sửa. Việc tiếp theo: chạy check_indexing_issues trên mười landing page nhiều click nhất, rồi xem bảy ngày tới auth có đứt đúng dự đoán.

This article was originally published on NextFuture. Follow us for more fullstack & AI engineering content.

DEV Community