gmail-mcp

Коннектор Gmail для MCP-клиентов. Один сервер, много аккаунтов Gmail через OAuth refresh-токены. Отправляет настоящие MIME-сообщения (вложения по пути к файлу, актуальные подписи, подтверждение после отправки). Читает и сортирует почту, не сбрасывая мегабайты base64 в модель.

Не обёртка вокруг размещённого Google Gmail MCP — этот сервер собирает RFC822 на хосте и обращается напрямую к gmail.googleapis.com.

Возможности

• Мультиаккаунтный OAuth — добавление почтовых ящиков через accounts_add; токены хранятся локально (права 0600)

• Отправка / ответ / пересылка — сервер собирает MIME, только пути к файлам исходящих, лимит 25 МБ, ключи идемпотентности, подтверждение при успехе

• Чтение / сортировка — поиск (цепочки + пагинация), получение цепочки/письма, метки, архив/корзина, черновики

• Вложения — отправка из ~/Outbox (настраивается); загрузка в ~/Inbox (настраивается)

• Двойной транспорт — stdio для локальных обвязок; Streamable HTTP за шлюзом для удалённых клиентов

Related MCP server: Gmail MCP Server

Требования

• Python 3.12+ (в разработке используется 3.13 через pyenv)

• OAuth-клиент Google Cloud для настольных приложений (client id + secret)

• macOS для включённых скриптов LaunchAgent (HTTP-сервис); Linux подходит для ручного запуска

Быстрый старт

git clone https://github.com/iXanadu/gmcp.git
cd gmcp

# Python 3.12+ (example with pyenv)
pyenv virtualenv 3.13 gmail-mcp-3.13
pyenv local gmail-mcp-3.13
pip install -e '.[dev]'

# Config (see examples/)
cp examples/.env.example .env
cp examples/.keys.example .keys
chmod 600 .keys

# Sanity check
gmail-doctor

Заполните .keys своими учётными данными Google OAuth и HTTP bearer-токеном перед запуском HTTP-транспорта.

Google Cloud Console (однократно)

Вам нужен OAuth-клиент для настольных приложений — не сервисный аккаунт и не делегирование на весь домен.

При первом accounts_add Google запрашивает согласие. Области доступа (scopes) фиксированы на сервере: чтение/отправка/сортировка почты плюс чтение подписи send-as (не кешируется).

Никаких имени пользователя/пароля, пароля приложения или вставленного refresh-токена в чате.

Подключение почтового ящика (accounts_add)

accounts_add открывает браузер для согласия Google. Он работает только на stdio-транспорте (gmail-mcp), не через HTTP.

gmail-mcp   # stdio — required for accounts_add and accounts_remove

Вызовите accounts_add из вашего MCP-клиента. Когда согласие будет завершено, сервер записывает адрес Gmail, возвращённый Google; этот адрес является ключом account для всех остальных инструментов.

Токены сохраняются в ~/.config/gmail-mcp/tokens/ (права 0600). При необходимости скопируйте этот каталог на любой другой хост, где работает тот же сервер.

Сервер без дисплея (нет локального браузера)

Обратный вызов OAuth — http://127.0.0.1:8767/oauth/callback. Машине без дисплея всё равно нужен браузер где-нибудь для страницы входа в Google. Два распространённых способа:

A — Проброс порта SSH (согласие на вашем ноутбуке)

На хосте без дисплея запустите stdio MCP / accounts_add. С вашего ноутбука:

ssh -L 8767:127.0.0.1:8767 user@headless-host

Откройте URL авторизации, который выводит сервер (или запустите accounts_add через ваш MCP-клиент при поднятом туннеле). Обратный вызов попадает на 127.0.0.1:8767 на хосте без дисплея через туннель.

B — Согласие на настольном компьютере, копирование токенов

Запустите accounts_add один раз на Mac или PC с браузером и теми же .env / .keys. После согласия скопируйте ~/.config/gmail-mcp/tokens/ на production-хост (те же пути, права 0600). Повторное согласие не требуется, если Google не отзовёт refresh-токен.

Схема развёртывания

Типичная схема в production:

┌─────────────────────┐         ┌──────────────────────────┐
│  Operator machine   │         │  MCP server (Linux/macOS) │
│  (browser for OAuth)│         │  gmail-mcp-http           │
│  accounts_add       │  copy   │  127.0.0.1:8879           │
│  token files ───────┼────────►│  + .env / .keys           │
└─────────────────────┘  tokens └───────────┬──────────────┘
                                            │
                              Cloudflare / gateway / TLS
                                            │
                                    Hand / remote MCP client

• Не выставляйте ноутбук оператора в публичный интернет для MCP HTTP. HTTP привязывается к loopback (127.0.0.1:8879) на сервере; обратный прокси завершает TLS и перенаправляет трафик на этот порт.

• OAuth выполняется там, где есть браузер (машина оператора или SSH-туннель). JSON-файлы с токенами копируются на сервер.

• Шлюз указывет на управляемый вами сервер (например, mcp.example.com), а не на OAuth-рабочую станцию.

• Сгенерируйте длинный случайный GMAIL_MCP_HTTP_BEARER_TOKEN; шлюз передаёт его как Authorization: Bearer ….

После развёртывания: gmail-doctor, ./scripts/start.sh (macOS LaunchAgent) или собственный systemd-юнит, затем accounts_list через HTTP для подтверждения токенов.

Конфигурация

Несекретные настройки находятся в .env; секреты — в .keys (не коммитьте их, когда они заполнены). Смотрите examplees/.env.example и examples/.keys.example.

Запускайте gmail-doctor после изменения конфигурации.

Транспорты

stdio (локальный)

gmail-mcp

Регистрирует все инструменты, включая accounts_add и accounts_remove.

Встройте в MCP-конфиг Cursor / Claude Code бинарник gmail-mcp из venv и cwd, указывающий на репозиторий (чтобы загружались .env / .keys).

Streamable HTTP (шлюз)

gmail-mcp-http

По умолчанию привязывается к 127.0.0.1:8879. Требуется Authorization: Bearer <GMAIL_MCP_HTTP_BEARER_TOKEN>; запросы без действительного токена получают 401.

Ручной список разрешений (только HTTP): инструменты чтения/сортировки плюс send, reply, forward, draft_create, draft_send, accounts_list и gmail_status. Управление аккаунтами остаётся на stdio.

Сервис macOS (пользовательский LaunchAgent)

./scripts/start.sh    # install plist → ~/Library/LaunchAgents, load
./scripts/stop.sh
./scripts/restart.sh

Отредактируйте пути в launchd/com.gmail-mcp.plist, если ваш checkout или имя pyenv отличается. Логи сохраняются в logs/.

На Linux запускайте gmail-mcp-http под systemd с той же привязкой к loopback — см. Схема развёртывания выше.

Инструменты

Каждый инструмент, кроме accounts_list, accounts_add и gmail_status, требует аргумент account (адрес Gmail).

Правила отправки (сводка)

• Вложения: { "path": "/absolute/or/under/outbox/file.pdf" } — без inline base64

• Актуальная подпись Gmail добавляется при отправке (не кешируется)

• Опциональный footer после подписи

• Возвращает подтверждение: размеры, hrefs, ok false → ошибка инструмента (например, обрезанное вложение или переписанный google.com/url)

Тесты

pytest tests/ -v

Использует имитацию Gmail HTTP; живой почтовый ящик не требуется.

Спецификация

Требования к продукту: docs/specs/gmail-mcp-spec.md

Лицензия

Apache-2.0