Google Analytics + AdSense Remote MCP

Remote MCP-сервер только для чтения для GA4 и AdSense Management API v2, работающий на Cloudflare Workers. Для HTTP-маршрутизации используется Hono, для MCP transport — createMcpHandler(), а для OAuth-авторизации клиента — Cloudflare Access Managed OAuth.

Один Worker привязан к одной паре Google OAuth refresh token и обрабатывает все GA4-свойства и AdSense-аккаунты, доступные для чтения этому Google-аккаунту. Нельзя подменить OAuth-учётные данные, хосты Google API или операции записи при вызовах инструментов.

Развёртывание в один клик на Cloudflare

Кнопка клонирует этот публичный GitHub-репозиторий в ваш собственный аккаунт, запрашивает имя Worker и следующие настройки, затем выполняет сборку и развёртывание.

• Несекретные настройки: CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD

• Secret: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN

Перед нажатием кнопки получите GOOGLE_REFRESH_TOKEN, авторизовав только read-only scope, как описано ниже. Включение Cloudflare Access Application и Managed OAuth выполняется самостоятельно после развёртывания.

Related MCP server: Google Analytics MCP server on Cloudflare Workers

Эндпоинты

Инструменты MCP

• ga4_run_report, ga4_run_realtime_report, ga4_run_pivot_report, ga4_run_funnel_report

• ga4_get_metadata, ga4_check_compatibility

• ga4_admin_read: операции GET/list для accountSummaries, accounts, properties в GA4 Admin API v1alpha.

• adsense_generate_report

• adsense_read: операции GET/list для accounts в AdSense Management API v2.

Все инструменты помечены как read-only в MCP, а входные данные проверяются с помощью Zod. Не принимаются внешние URL, произвольные HTTP-заголовки или произвольное выполнение POST/PUT/PATCH/DELETE. Сырые ошибки Google не включаются в ответы MCP, но полное содержимое выводится в Worker Logs вашего аккаунта Cloudflare для диагностики сбоев.

Подготовка Google OAuth

1. В проекте Google Cloud включите Google Analytics Data API, Google Analytics Admin API и AdSense Management API.

2. Настройте экран согласия OAuth, запрашивая только https://www.googleapis.com/auth/analytics.readonly для GA4 и https://www.googleapis.com/auth/adsense.readonly для AdSense.

3. В разделе Credentials создайте OAuth Client ID, выбрав тип приложения Desktop app. AdSense не поддерживает service account, поэтому требуется Installed Application flow.

4. Refresh token может не отображаться повторно, поэтому при выпуске сохраните его в надёжном менеджере паролей. Не размещайте его в репозитории, Issue, логах CI или wrangler.jsonc.

Google быстро истекает срок действия access token. Worker при каждом выполнении инструмента MCP повторно получает access token через refresh token grant, поэтому Worker не нужно хранить токены постоянно.

Получение refresh token с помощью Python

Работает только с Python 3.10 и выше, дополнительные пакеты не требуются. scripts/get_google_refresh_token.py использует PKCE, ожидает локальный callback и не сохраняет учётные данные, access token или refresh token в файлы.

Настройка redirect URI в Google Cloud Console

Этот Worker не получает callback напрямую от Google. OAuth-клиент, созданный в Credentials, обязательно должен быть Desktop app. Для Desktop app не нужно настраивать Authorized redirect URIs или Authorized JavaScript origins в Cloud Console.

Python-скрипт при запуске выбирает свободный локальный порт и отправляет в Google, например, такой loopback redirect URI:

http://127.0.0.1:54321/callback/

Это loopback callback, разрешённый Google для Desktop app. Не регистрируйте https://<worker-host>/callback, https://<worker-host>/mcp или URL Cloudflare Access в качестве redirect URI для OAuth-клиента Google. Также избегайте использования этого скрипта с OAuth-клиентом типа Web application.

python scripts/get_google_refresh_token.py

Будет запрошен ввод GOOGLE_CLIENT_ID и GOOGLE_CLIENT_SECRET. В браузере войдите в Google-аккаунт, который будет использовать Worker, и авторизуйте только следующие read-only scope.

Чтобы отменить авторизацию в браузере, нажмите Ctrl+C в ожидающем терминале. Локальный callback listener закроется, и скрипт завершится без сохранения токенов.

• https://www.googleapis.com/auth/analytics.readonly

• https://www.googleapis.com/auth/adsense.readonly

Скопируйте единственную строку, отображаемую при успехе, и введите её в поле Secret GOOGLE_REFRESH_TOKEN на Deploy Button или в следующую интерактивную команду.

pnpm wrangler secret put GOOGLE_REFRESH_TOKEN

Если Client ID / secret также не заданы, настройте их аналогично.

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET

Если экран согласия Google OAuth остаётся в статусе External + Testing, refresh token обычно истекает через 7 дней. Перед продолжением использования перейдите в Production и завершите проверку, требуемую Google. При возникновении invalid_grant отзовите доступ этого приложения в Google-аккаунте, затем повторно запустите скрипт и обновите Worker Secret.

Локальная разработка

Требуется: Node.js 20 или выше, Corepack, аккаунт Cloudflare с доступом к Cloudflare Zero Trust.

corepack enable
pnpm install
Copy-Item .dev.vars.example .dev.vars
pnpm check
pnpm dev --local

В .dev.vars укажите реальные учётные данные Google. Этот файл не добавляется в Git.

Развёртывание на Cloudflare

1. В wrangler.jsonc измените name, CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD на значения вашей конфигурации Cloudflare Access.

2. Задайте Secret по отдельности.

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET
pnpm wrangler secret put GOOGLE_REFRESH_TOKEN
pnpm run deploy

3. В Cloudflare Zero Trust Dashboard создайте MCP server application для https://<worker-host>/mcp вашего Worker.

4. Создайте Access Policy, разрешающую нужные адреса электронной почты или ID group, и запретите доступ остальным пользователям.

5. В Advanced settings включите Managed OAuth. Убедитесь, что Application Audience tag и Team Domain совпадают с настройками Worker.

Cloudflare Access отвечает за OAuth discovery, Dynamic Client Registration, Authorization Code Flow, PKCE и обновление access token. Не добавляйте собственные /authorize, /token, /register внутри Worker.

Подключение MCP-клиента

MCP endpoint: https://<worker-host>/mcp. При первом подключении откроется окно входа и авторизации Cloudflare Access.

• Inspector: запустите npx @modelcontextprotocol/inspector@latest, подключите endpoint и выполните Scan / List Tools для всех инструментов.

• Codex и др.: зарегистрируйте endpoint в конфигурации Remote MCP с поддержкой OAuth.

• ChatGPT: в Developer mode зарегистрируйте endpoint в Custom MCP app / connector, завершите OAuth-авторизацию, затем выполните Tool Scan. Доступность ChatGPT зависит от тарифного плана, настроек Workspace и региона.

Проверка

pnpm check

check последовательно выполняет ESLint, TypeScript, Vitest, синхронизацию типов Worker binding и wrangler deploy --dry-run. Автоматические запросы к реальному Google-аккаунту не выполняются. После развёртывания через Access с помощью Inspector и используемого MCP-клиента выполните по одному отчёту GA4 и AdSense.

Диагностика ошибок Google API

При сбое Google API Worker выводит JSON-событие диагностики в Cloudflare Workers Logs. В нём без сокращений выводятся тело HTTP-ответа Google, URL и тело запроса, имя исключения, сообщение и стек-трейс. Это отладочная настройка, доступная только тем, кто может просматривать логи вашего аккаунта Cloudflare. Если вы планируете передавать, публиковать или делиться логами, заранее отключите эту подробную запись. В ответы MCP она по-прежнему не включается.

pnpm wrangler tail --format json

Пример: {"event":"google_request_failed","tool":"ga4_run_report","category":"google_api","upstreamStatus":403,"error":{"request":{"url":"..."},"responseBody":"...","stack":"..."}}. oauth_refresh — сбой обновления refresh token, google_api — отказ GA4 / AdSense API, unexpected — непредвиденный сбой, например сетевой.

Лицензия

MIT License