Google не даёт просто выписать токен и пойти работать. Вместо этого — проект, приложение, клиент, экран согласия, callback-сервер. Если вы уже потратили час и всё ещё не понимаете, что от вас хотят — эта статья для вас. Разбираем три реальных пути подключения и объясняем, почему Google устроен именно так.
Три способа, и только один из них «просто работает»
Самый быстрый путь — встроенный коннектор вашего AI-провайдера. В Claude это кнопка Connect в интерфейсе claude.ai: нажал, авторизовался, готово. ChatGPT работает аналогично. Если вы используете только веб-интерфейс или Claude Desktop — остановитесь здесь, дальше вам не нужно.
Проблема возникает, когда вы выходите за пределы UI. Claude Code CLI, запущенный в терминале, коннекторы claude.ai уже не видит. Open-source агенты — тоже. Там нужны два других варианта: MCP-сервер или прямой вызов Google API через CLI-обёртку.
| Способ | Когда подходит | Ограничения |
|---|---|---|
| Коннектор провайдера | Только UI / Claude Desktop | Нет доступа из CLI и open-source агентов |
| MCP-сервер | Хочется стандартного протокола | Официальный MCP сырой, мало методов |
| Самописный CLI-клиент | CLI-агенты, кастомные требования | Нужно один раз написать / сгенерировать |
Официальные MCP от Google на момент написания (сентябрь 2026) работают частично: в Calendar нет доступа к контактам через People API, а MCP для Drive может вообще не запуститься. Сторонние MCP вроде @piotr-agier/google-drive-mcp существуют, но добавляют в контекст агента лишние методы и могут содержать баги. Практичнее всего — попросить агента написать минимальный CLI-клиент под ваши задачи, а потом вызывать его как обычную команду в терминале.
Почему Google не даёт просто токен
Google Cloud изначально проектировался для компаний, а не для одного разработчика с ноутбуком. Большинство сервисов поддерживают PAT (Personal Access Token): создал, выдал права, вставил в .env. Google так не умеет.
Вместо этого — OAuth 2.0. Механизм рабочий, но требует понять несколько сущностей:
Google Cloud Project — контейнер для всего. По умолчанию у вас уже есть «My First Project».
Google Auth Platform — раздел внутри проекта, где настраивается «приложение». Приложение — это сущность, которой пользователь даёт разрешения. Один проект = одно приложение. Название, ссылка на homepage и privacy policy — заполните чем угодно, хоть ссылкой на GitHub.
Client (Клиент) — набор учётных данных внутри приложения, привязанный к платформе (Desktop, Web и т.д.). Именно отсюда скачивается JSON с client_id и client_secret.
Scopes — конкретные разрешения: читать почту, создавать события в календаре и т.д. Запрашиваются при авторизации.
{
"installed": {
"client_id": "1234567890-abc123.apps.googleusercontent.com",
"project_id": "my-project-123456",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_secret": "GOCSPX-...",
"redirect_uris": ["http://localhost"]
}
}client_secret здесь не особо секретный: сам по себе он доступ к API не даёт, только подтверждает client_id при обмене кода на токен.
Как работает OAuth-флоу на практике
Вот что происходит, когда ваш CLI-клиент или MCP-сервер запрашивает доступ:
- Клиент формирует ссылку на
accounts.google.comс параметрами: какое приложение, какие scopes, куда вернуть результат. - Вы открываете ссылку в браузере, видите экран согласия, нажимаете «Разрешить».
- Google редиректит браузер на callback-адрес — в случае Desktop-клиента это
http://localhost:<порт>. - Ваш клиент в этот момент держит маленький веб-сервер на этом порту и ловит запрос.
- В запросе — одноразовый код, не токен. Клиент сам обменивает его на токены прямым запросом к
https://oauth2.googleapis.com/token.
После этого python-библиотека google-auth сохраняет токены примерно в таком формате:
{
"token": "ya29.a0...",
"refresh_token": "1//0g...",
"token_uri": "https://oauth2.googleapis.com/token",
"client_id": "1234567890-abc123.apps.googleusercontent.com",
"client_secret": "GOCSPX-...",
"scopes": ["https://www.googleapis.com/auth/calendar"]
}refresh_token — долгоживущий, именно он позволяет получать новые token без повторной авторизации через браузер.
Минимальный CLI-клиент: что попросить у агента
Если вы решили идти по пути самописного клиента, дайте агенту конкретное задание. Пример промпта:
Напиши CLI на Python, который:
1. Читает credentials.json (OAuth Desktop-клиент Google)
2. При первом запуске открывает браузер для авторизации и сохраняет token.json
3. Поддерживает команды:
- calendar list --days 7
- calendar create --title "..." --start "2026-09-10T10:00" --end "..." --attendees "a@b.com,c@d.com"
- drive list --folder-id "..."
- drive upload --file ./report.pdf --folder-id "..."
Scopes: calendar, drive.file, contacts.readonlyАгент напишет клиент, вы один раз пройдёте авторизацию в браузере, токены сохранятся в token.json. Дальше агент вызывает CLI как обычную bash-команду — никаких MCP, никакого лишнего контекста.
python gcal.py calendar list --days 7
python gcal.py calendar create --title "Sync" --start "2026-09-15T14:00" --end "2026-09-15T15:00"Где это ломается
Настройка на сервере без браузера. Callback приходит на localhost, но браузера на сервере нет. Решение — SSH-туннель: пробросьте локальный порт на сервер (ssh -R 8080:localhost:8080 user@server), пройдите авторизацию локально, скопируйте token.json на сервер.
Экран согласия в статусе «Testing». Пока приложение не прошло верификацию Google, refresh_token живёт 7 дней, потом отзывается. Для личного использования переведите приложение в статус «In production» — верификация не нужна, если вы единственный пользователь.
Официальный MCP Calendar без People API. Если агенту нужны контакты для автодополнения участников встречи — официальный MCP не поможет. Придётся добавить scope https://www.googleapis.com/auth/contacts.readonly и вызывать People API вручную.
Протухший `token`. ya29.a0... живёт около часа. Библиотека google-auth обновляет его автоматически при наличии refresh_token. Если пишете клиент не на Python — убедитесь, что реализовали refresh-логику.
Что попробовать дальше
Когда базовое подключение работает, следующий шаг — дать агенту доступ к Google Tasks и Google Meet через те же scopes в одном клиенте. Также стоит посмотреть на agno Google Calendar Context Provider — он оборачивает OAuth-флоу в готовый провайдер с переменными окружения GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET, что удобно для быстрого старта в Python-агентах.
FAQ
Нужно ли платить за Google Cloud, чтобы подключить Calendar и Drive?
Нет. Google Calendar API и Google Drive API входят в бесплатный уровень с достаточными лимитами для личного использования. Платить нужно только если вы превышаете квоты — для одного агента это практически нереально.
Чем отличается OAuth Desktop-клиент от Web-клиента?
Desktop-клиент использует http://localhost как redirect URI и не требует публичного домена. Web-клиент нужен, если callback должен приходить на внешний URL. Для агента на локальной машине — всегда Desktop.
Можно ли использовать один token.json для нескольких агентов?
Да, если они запускаются под одним пользователем и читают один файл. Главное — не запускать их одновременно с записью в файл, иначе возможна гонка при обновлении токена.
Почему refresh_token иногда исчезает из ответа Google?
Google возвращает refresh_token только при первой авторизации или если пользователь явно отозвал доступ и авторизовался заново. Если токен не сохранился — отзовите доступ в myaccount.google.com/permissions и пройдите авторизацию снова.
Как добавить новый scope, не заставляя пользователя заново авторизоваться?
Никак — при изменении набора scopes нужна повторная авторизация. Поэтому лучше сразу запросить все нужные разрешения с запасом, чем добавлять их по одному.
