Metadata-Version: 2.4
Name: heroseo-mcp
Version: 0.1.0
Summary: MCP Server cho Google Analytics 4 + Google Search Console (dùng với Claude.ai / Claude Desktop)
Project-URL: Homepage, https://dichvuseotongthe.vn
Author-email: HeroSEO <teamheroseo@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,ga4,google-analytics,gsc,mcp,search-console,seo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.10
Requires-Dist: google-analytics-admin>=0.22.7
Requires-Dist: google-analytics-data>=0.18.10
Requires-Dist: google-api-python-client>=2.130.0
Requires-Dist: google-auth-httplib2>=0.2.0
Requires-Dist: google-auth-oauthlib>=1.2.0
Requires-Dist: google-auth>=2.29.0
Requires-Dist: mcp[cli]>=1.2.0
Description-Content-Type: text/markdown

# HeroSEO MCP — GA4 + Search Console cho Claude

MCP Server giúp **Claude** (Claude Desktop) đọc dữ liệu từ **Google Analytics 4** và
**Google Search Console** bằng tài khoản Google của bạn — hỏi bằng tiếng tự nhiên, Claude tự gọi API.

> Read-only · token lưu cục bộ trên máy bạn · không cần tự tạo Google Cloud project.

`mcp-name: vn.dichvuseotongthe/heroseo-mcp`

---

## Cài đặt nhanh

```bash
uv tool install heroseo-mcp
```

Thêm vào file cấu hình Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "heroseo-mcp": {
      "command": "uvx",
      "args": ["heroseo-mcp"]
    }
  }
}
```

Khởi động lại Claude Desktop → hỏi *"Liệt kê các GA4 property của tôi."* → lần đầu Claude sẽ mở
trình duyệt cho bạn đăng nhập Google (cấp quyền Analytics + Search Console, read-only). Xong là dùng được.

👉 Hướng dẫn chi tiết từng bước: [HOW_TO_USE.md](HOW_TO_USE.md).

---

## Tools

### Google Analytics 4
| Tool | Mô tả |
|---|---|
| `ga4_list_accounts` | Liệt kê tất cả GA4 accounts |
| `ga4_list_properties` | Liệt kê GA4 properties (websites/apps) |
| `ga4_run_report` | Report tuỳ chỉnh — dimensions, metrics, date range, sort |
| `ga4_run_realtime_report` | Users đang active trong 30 phút gần nhất |
| `ga4_get_metadata` | Dimensions/metrics khả dụng cho 1 property |

### Google Search Console
| Tool | Mô tả |
|---|---|
| `gsc_list_sites` | Liệt kê tất cả GSC properties |
| `gsc_query_search_analytics` | Top queries / pages / countries / devices — clicks, impressions, CTR, position |
| `gsc_inspect_url` | Inspect 1 URL — index status, crawl, sitemap, rich results |
| `gsc_list_sitemaps` | Liệt kê sitemaps đã submit |
| `gsc_get_sitemap` | Chi tiết 1 sitemap — errors, warnings, last download |

---

## Ví dụ prompt

> - "Property 123456789: 10 trang được xem nhiều nhất 28 ngày qua."
> - "Site https://example.com/ : top 20 query nhiều impression nhất tháng vừa rồi."
> - "Trang nào của tôi đang rank cho từ khoá 'dịch vụ seo'?"
> - "URL https://example.com/blog/abc đã được Google index chưa?"
> - "So sánh sessions từ organic search tuần này với tuần trước cho property 123456789."

---

## Quyền & bảo mật

- Scope OAuth (read-only): `analytics.readonly` + `webmasters.readonly` — không sửa/xoá được dữ liệu.
- Token lưu cục bộ tại `~/.heroseo-mcp/token.json`, **không** gửi về nhà phát hành.
- Thu hồi quyền bất cứ lúc nào tại [myaccount.google.com/permissions](https://myaccount.google.com/permissions).
- [Chính sách bảo mật](https://dichvuseotongthe.vn) · liên hệ: teamheroseo@gmail.com

## License

[MIT](LICENSE)
