gmail-mcp-server

MCP-сервер, предоставляющий один инструмент, send_email, который отправляет сообщения Gmail (с возможностью прикрепления файлов) через Gmail API. Создан для использования в качестве локального stdio MCP-сервера внутри Claude Code.

Область действия намеренно узкая: только gmail.send (без доступа на чтение/изменение почтового ящика) — минимальные привилегии для инструмента, единственная задача которого — отправлять почту.

Этот README написан по итогам реальной первой настройки, включая все ошибки, которые возникали по ходу дела. Проходите его сверху вниз — и вы не должны столкнуться ни с одной из них.

Примечание по PowerShell: && не работает как разделитель команд в Windows PowerShell (это синтаксис bash/cmd). Все команды, состоящие из нескольких частей, ниже записаны отдельными строками; либо используйте ;, если нужна одна строка: cd C:\Users\GaneshGupta\gmail-mcp-server; python auth_setup.py

1. Google Cloud — включите API и создайте OAuth-учётные данные

В консоли Google этот раздел недавно переименовали из «OAuth consent screen» в Google Auth Platform, а настройки разнесли по отдельным страницам левого меню (Branding / Audience / Clients / Data Access / Verification Center). В шагах ниже используются актуальные названия.

1. Перейдите на console.cloud.google.com. Создайте новый проект или используйте существующий.

2. APIs & Services → Library → найдите «Gmail API» → Enable.

3. APIs & Services → OAuth consent screen (вы попадёте в новый раздел Google Auth Platform) → заполните страницу Branding:

   • App name: любое, например gmail-mcp-tool

   • User support email: ваш адрес Gmail

   • Developer contact email: ваш адрес Gmail

   • Поля logo/App domain пока оставьте пустыми — вы вернётесь к App domain на шаге 4, если столкнётесь с ошибкой «incomplete configuration». Не заполняйте их на всякий случай; делайте это только если действительно увидите эту ошибку.

4. Страница Audience (левое меню) → в разделе Test users → + Add users → укажите свой собственный адрес Gmail (тот, с которого будет отправляться почта) → Save.

   Если «Add users» заблокировано жёлтым баннером с текстом «Your app's OAuth configuration is incomplete... Please visit the Branding page» — это происходит потому, что gmail.send — чувствительная область доступа, для которой поля App domain должны быть непустыми даже для приложения только в режиме Testing. Исправление:

   • Перейдите в Branding → App domain и заполните:

     • Application home page: https://example.com

     • Application privacy policy link: https://example.com/privacy

     • Application terms of service link: https://example.com/terms

   • После этого появится поле Authorized domains. Введите только домен без префикса https://:

     • Правильно: example.com

     • Неправильно (отклоняется с ошибкой «Invalid domain: must not specify the scheme»): https://example.com

   • Нажмите Save на странице Branding (должно появиться уведомление «Branding changes saved!»).

   • Вернитесь в Audience → Add users и попробуйте снова — на этот раз должно пройти.

   Эти URL не обязаны быть реальными/рабочими — Google не проверяет их, пока приложение находится в статусе Testing, ему просто нужно, чтобы поля были заполнены.

5. Страница Clients (левое меню) → + Create client:

   • Application type: Desktop app

   • Name: любое, например gmail-mcp-desktop

   • Create → Download JSON (кнопка появляется сразу после создания)

6. Скачанный файл будет называться примерно так: client_secret_<long-id>.apps.googleusercontent.com.json. Переименуйте его точно в client_secret.json и переместите в:

   C:\Users\GaneshGupta\gmail-mcp-server\credentials\client_secret.json

   Точное имя файла важно — gmail_auth.py ищет файл по этому имени и выбрасывает FileNotFoundError, если имя не совпадает (это самая частая ошибка на этом шаге).

Related MCP server: Gmail MCP Server

2. Установка зависимостей

cd C:\Users\GaneshGupta\gmail-mcp-server
pip install -r requirements.txt

3. Одноразовый вход

python auth_setup.py

Что происходит:

1. Откроется окно браузера с обычным входом в Google.

2. Вы попадёте на экран «Google hasn't verified this app». Это ожидаемо — это ваш собственный OAuth-клиент в режиме Testing, запрашивающий чувствительную область доступа. Нажмите Continue (в старом интерфейсе: Advanced → Go to [app name] (unsafe)).

3. Предоставьте разрешение «Send email on your behalf».

4. Браузер покажет «The authentication flow has completed. You may close this window.»

5. В терминале появится Authorized. Token saved to ...credentials\token.json.

Если на шаге 2 вместо этого отображается Error 403: access_denied / «has not completed the Google verification process... can only be accessed by developer-approved testers» — вашего адреса Gmail ещё нет в списке Audience → Test users. Вернитесь к шагу 1.4 выше.

Сделайте это один раз. После этого server.py лишь молча обновляет сохранённый токен — браузер больше никогда не открывается сам.

4. Проверка токена (необязательно, но рекомендуется)

python -c "from gmail_auth import load_credentials; c = load_credentials(); print('valid:', c.valid); print('scopes:', c.scopes); print('has refresh token:', bool(c.refresh_token))"

Ожидайте valid: True, scopes: ['https://www.googleapis.com/auth/gmail.send'], has refresh token: True.

5. Регистрация в Claude Code

claude mcp add gmail-sender --scope user -- python C:\Users\GaneshGupta\gmail-mcp-server\server.py

--scope user регистрирует сервер глобально — он становится доступен во всех сессиях Claude Code на этой машине, а не только в той, где вы выполнили команду. В уже запущенной сессии он задним числом не появится — MCP-серверы загружаются при старте сессии, поэтому откройте новый терминал / новую сессию claude, чтобы увидеть его.

Проверка:

claude mcp list

В списке вы должны увидеть gmail-sender.

6. Использование

В любой сессии Claude Code (после регистрации выше) просто попросите на естественном языке:

Отправь письмо на jane@example.com с темой «Following up» и текстом «...» — приложи C:\path\to\file.pdf

Claude Code напрямую вызовет инструмент send_email. Никакой дополнительной настройки для каждой сессии не требуется.

Справочник по инструменту

send_email(to, subject, body, attachments=None, cc=None, bcc=None, html=False)

• to / cc / bcc: адреса через запятую

• attachments: список абсолютных локальных путей к файлам, суммарный лимит — 15MB (потолок Gmail для raw-отправки — 25MB; 15MB исходных файлов оставляют запас на раздувание base64 + заголовки)

• html: установите true, чтобы отправить HTML-тело вместо обычного текста

• Возвращает {status, message_id, thread_id, to, subject, attachment_count}

Таблица неполадок

Примечания

• credentials/client_secret.json и credentials/token.json находятся в .gitignore — никогда не коммитьте их.

• Чтобы отправлять с другого аккаунта Gmail, удалите credentials/token.json и снова запустите auth_setup.py.