gmail-mcp

Многопрофильный Gmail MCP-сервер для ИИ-агентов (Claude Code и всего остального, что говорит на MCP) с одной главной целью дизайна: агент может свободно читать и создавать черновики, но каждую отправку должен одобрить человек.

Создан потому, что облачные коннекторы Gmail привязываются к одному аккаунту за раз и отправляют без каких-либо преград. Этот сервер связывает любое количество аккаунтов Gmail с короткими алиасами (work, school, ...) и разделяет возможности по уровню риска:

Сервер намеренно зарегистрирован как gmail-accounts (а не gmail): если вы также запускаете облачный коннектор Gmail, почти одинаковые имена инструментов заставят агента прочитать не тот почтовый ящик и уверенно выдать ложноотрицательный результат.

Как работает шлюз отправки

1. Агент подготавливает черновик и просит вас одобрить его.

2. Вы запускаете gmail-approve в своём терминале, просматриваете точный RFC822-пейлоад и получаете одноразовый токен, привязанный к хешу содержимого этого черновика.

3. Агент вызывает инструмент отправки с токеном. Не тот черновик, изменённый черновик, повторно использованный токен, истёкший токен — всё отклоняется.

Инструмент отправки также несёт anthropic/requiresUserInteraction, поэтому Claude Code запрашивает подтверждение человека даже в режиме bypassPermissions. CLI токена — это предохранитель от ошибок; запрос обвязки — принудительная граница.

Related MCP server: Gmail Multi-Inbox MCP Server

Настройка

Требуются Python 3.12+ и uv.

1. Google Cloud OAuth-клиент

Создайте проект на console.cloud.google.com, включите Gmail API, создайте OAuth-клиент типа Desktop app и скачайте JSON в:

~/.config/gmail-mcp/client_secret.json

2. Объявите свои аккаунты

~/.config/gmail-mcp/accounts.json:

{
  "accounts": [
    { "alias": "personal", "email": "alice.personal@gmail.com" },
    { "alias": "work",     "email": "alice.work@gmail.com" }
  ]
}

Добавление аккаунта позже — это правка конфига плюс один запуск авторизации; файл перечитывается при каждом вызове, поэтому перезапуск не нужен.

3. Авторизуйте каждый аккаунт

uv sync
scripts/auth-all.sh          # runs the OAuth flow once per alias, skips done ones

Каждое разрешение проверяется на соответствие алиасу: авторизация не того Google-аккаунта в браузере обнаруживается и отклоняется, а не сохраняется молча.

4. Зарегистрируйте в Claude Code

claude mcp add gmail-accounts -- uv run --directory /path/to/gmail-mcp --frozen --no-sync gmail-mcp

Повседневное использование

Каждый инструмент принимает алиас account. Просите агента, например, «найди в work переписку по счёту» или «создай черновик ответа в personal». Когда придёт время отправлять:

gmail-approve            # lists pending sends, shows the payload, mints a token

Проверка состояния:

uv run gmail-mcp-health

Примечания по безопасности

• Секреты никогда не попадают в репозиторий: client_secret.json и токены каждого аккаунта хранятся в ~/.config/gmail-mcp/ (переопределяется через GMAIL_MCP_CONFIG).

• Все записи конфигурации атомарны (tmp + fsync + rename); сбой в середине записи никогда не оставляет повреждённый файл.

• stdout — это канал JSON-RPC; ничто в пакете не может вызывать print() (проверяется ruff T201), поэтому диагностика не может нарушить протокол.

Тесты

uv run pytest