Gmail MCP Gateway

MCP-сервер, который предоставляет AI-агентам полный доступ на чтение и организацию к нескольким аккаунтам Gmail — и не даёт возможности отправлять, помещать в корзину или удалять письма.

                     Gmail MCP Gateway

        ALLOWED                        FORBIDDEN
        ───────                        ─────────
        Search                         Send
        Read messages                  Send draft
        Read threads                   Trash
        Read attachments               Delete
        Create drafts                  Mark spam
        Edit drafts                    Gmail settings
        Archive                        Forwarding rules
        Read / unread                  Arbitrary API calls
        Labels

Гарантия обеспечивается на уровне кода приложения, а не инструкциями клиенту. Ошибочный, скомпрометированный или заражённый путём инъекции подсказок MCP-клиент не может отправить электронное письмо через этот шлюз, потому что не существует пути кода, который бы это позволил.

Содержание

• Быстрый старт — от клонирования до рабочего состояния за пять шагов

• Переменные окружения — что задать и как создать

• Запуск — stdio, HTTP, systemd, Docker

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

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

• Администрирование

• Как обеспечивается граница

• Модель безопасности

• Надёжность

• Тестирование

• Устранение неполадок

Related MCP server: imap-mcp

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

Требуется Python 3.11+. Пять шагов, примерно десять минут, большую часть из которых вы проведёте в консоли Google.

1. Установка

git clone <this-repo> gmail-mcp-gateway
cd gmail-mcp-gateway
uv sync                                  # or: python -m venv .venv && .venv/bin/pip install -e .
.venv/bin/gmail-mcp-gateway --version

При желании поместите его в PATH, чтобы примеры ниже читались более естественно:

export PATH="$PWD/.venv/bin:$PATH"

2. Создание OAuth-клиента Google

Одноразовое, бесплатное и общее для всех учётных записей, которые вы добавите позже.

1. Создайте проект на https://console.cloud.google.com/.

2. APIs & Services → Library → включите Gmail API.

3. APIs & Services → OAuth consent screen → External, заполните обязательные поля, добавьте свой аккаунт Google в Test users.

4. Опубликуйте приложение (проверка не требуется, пока вы единственный пользователь). Если пропустить этот шаг, приложение останется в режиме «Тестирование», где Google аннулирует токены обновления через 7 дней, и вам придётся авторизоваться каждую неделю.

5. Credentials → Create credentials → OAuth client ID → Desktop app → Скачать JSON.

Здесь вы не выбираете области доступа. Шлюз запрашивает ровно то, что необходимо во время авторизации, и отказывается запрашивать что-либо за пределами Gmail.

3. Установка OAuth-клиента

install -Dm600 ~/Downloads/client_secret_*.json \
  ~/.local/share/gmail-mcp-gateway/secrets/oauth_client.json

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

4. Авторизация учётной записи

gmail-mcp-gateway accounts add personal

Откроется браузер; подтвердите запрошенные разрешения, оставив все флажки установленными (шлюз громко завершится с ошибкой, а не будет работать наполовину, если какое-либо разрешение не предоставлено). Токен обновления сохраняется в зашифрованном виде, и с этого момента шлюз работает без участия пользователя.

Добавьте столько, сколько нужно — каждая учётная запись получает собственное согласие, токен обновления, ключ шифрования, ограничение скорости и журнал аудита:

gmail-mcp-gateway accounts add work
gmail-mcp-gateway accounts add newsletters --read-only   # Google itself refuses writes

5. Проверка

gmail-mcp-gateway health          # exit 0 = ready, 2 = something is wrong

[ok  ] directories      config=/home/you/.config/gmail-mcp-gateway ...
[ok  ] database         /home/you/.local/share/gmail-mcp-gateway/gateway.db
[ok  ] master_key       loaded
[ok  ] oauth_client     configured
[ok  ] accounts         1/1 authorized

gmail-mcp-gateway 1.0.0: healthy

Затем укажите ваш MCP-клиент — см. Подключение MCP-клиента — или сначала опробуйте его:

uv run python scripts/try-it.py --account personal

Переменные окружения

Для обычной локальной установки ни одна из них не требуется. Быстрый старт выше не задаёт ни одной переменной окружения. По умолчанию конфигурация помещается в ~/.config, данные и секреты — в ~/.local/share, а ключ шифрования генерируется автоматически.

Они существуют для контейнеров, systemd-юнитов и менеджеров секретов — мест, где файл на диске является неподходящим механизмом.

¹ Альтернатива secrets/oauth_client.json. Укажите файл или пару. ² При отсутствии шлюз создаёт secrets/master.key (режим 0600) при первом запуске.

Переменные окружения переопределяют config.toml, который, в свою очередь, переопределяет значения по умолчанию.

Генерация каждого значения

ID и секрет OAuth-клиента — из JSON-файла, скачанного на шаге 2 быстрого старта. Чтобы использовать переменные окружения вместо файла:

jq -r '.installed.client_id'     ~/Downloads/client_secret_*.json
jq -r '.installed.client_secret' ~/Downloads/client_secret_*.json

Мастер-ключ — 32 случайных байта, base64:

openssl rand -base64 32
# or, without openssl:
python3 -c "import base64,secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())"

Этот ключ расшифровывает сохранённые токены обновления. Если изменить его после добавления учётных записей, их учётные данные станут нечитаемыми, и для каждой учётной записи потребуется accounts reauth. Сделайте резервную копию вместе с каталогом данных.

Токен-носитель шлюза — не переменная окружения. Это то, что MCP-клиент отправляет через HTTP-транспорт, и он не связан ни с какими учётными данными Google. CLI создаёт его и сохраняет только SHA-256-хэш:

gmail-mcp-gateway token create my-agent

Простой текст выводится один раз и помещается в конфигурацию клиента.

Использование env-файла

Шлюз не читает .env автоматически — инструмент безопасности не должен молча поглощать секреты из любого каталога, в котором он был запущен. Скопируйте .env.example, в котором описана каждая переменная, и загрузите его явно:

cp .env.example .env       # already covered by .gitignore
$EDITOR .env
set -a && source .env && set +a
gmail-mcp-gateway health

systemd использует EnvironmentFile=; Docker Compose — env_file:.

Запуск

stdio — обычный выбор

Клиент запускает шлюз как дочерний процесс и общается через каналы. Ни порта, ни токена, ни сетевого воздействия. Учётные данные Google остаются внутри процесса шлюза; клиент видит только вызовы инструментов.

gmail-mcp-gateway serve --transport stdio

При запуске вручную он будет казаться зависшим — это нормально, он ожидает JSON-RPC на stdin. Обычно ваш MCP-клиент запускает его за вас.

Streamable HTTP — автономный сервис

Для долгоживущего сервиса или клиента, который не может запускать процессы.

gmail-mcp-gateway token create my-agent          # once; save the printed token
gmail-mcp-gateway serve --transport http --host 127.0.0.1 --port 8765

Конечная точка привязывается к loopback, требует токен-носитель и имеет защиту от DNS-ребдиндинга. GET /healthz не требует аутентификации и сообщает только о работоспособности.

Привязка к адресу, отличному от loopback, требует GMAIL_MCP_ALLOW_REMOTE_BIND=true, и даже в этом случае адрес, доступный в интернете, будет отклонён. Для удалённого клиента используйте туннель:

ssh -L 8765:127.0.0.1:8765 gateway-host

systemd

deploy/gmail-mcp-gateway.service запускается от имени специального системного пользователя в усиленной изолированной среде — ProtectSystem=strict, пустой CapabilityBoundingSet, фильтр seccomp, NoExecPaths для каталога данных. Инструкции по установке находятся в заголовке юнита. Авторизуйте учётные записи один раз, в интерактивном режиме, от имени пользователя службы перед её запуском.

Docker

deploy/Dockerfile и deploy/docker-compose.yml запускаются от имени не-root и только для чтения, все возможности отключены, порт опубликован только на loopback. Образ не содержит учётных данных; они находятся в томе /secrets.

docker compose -f deploy/docker-compose.yml up -d

Последовательность одноразовой авторизации — размещение OAuth-клиента, запуск процесса согласия с опубликованным портом перенаправления, создание токена — описана в комментариях в заголовке compose-файла.

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

stdio

{
  "mcpServers": {
    "gmail": {
      "command": "/absolute/path/to/gmail-mcp-gateway/.venv/bin/gmail-mcp-gateway",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Claude Code:

claude mcp add gmail -- /absolute/path/to/.venv/bin/gmail-mcp-gateway serve --transport stdio

HTTP

{
  "mcpServers": {
    "gmail": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer <token from `token create`>" }
    }
  }
}

Клиенты никогда не монтируют и не получают доступ к файлам учётных данных Google. При stdio клиент общается через канал; при HTTP он использует токен шлюза, не связанный с учётными данными Google.

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

Каждый инструмент принимает псевдоним account — учётной записи по умолчанию нет. Изменяющие инструменты принимают необязательный client_request_id для идемпотентности: повторный вызов с тем же идентификатором и аргументами возвращает первый результат вместо повторного действия.

Изменения работают с отдельными сообщениями, темами и пакетами (максимум 100 ID по умолчанию). Метки могут быть указаны как ID (Label_7) или отображаемые имена (Receipts).

Чтение и запись обрабатываются асимметрично там, где это важно: gmail_search с радостью отфильтрует по TRASH или установит include_spam_trash, потому что просмотр того, что уже есть, — это чтение. Применение этих меток отклоняется, потому что это переместило бы письма в корзину или пометило бы их как спам.

Ошибки

Сбои возвращаются как ошибки MCP-инструментов с isError: true и структурированной полезной нагрузкой как в текстовом блоке, так и в структурированном содержимом:

{"error": {
  "code": "forbidden_label",
  "message": "refusing to add label 'TRASH': moving messages to Trash is a forbidden capability of this gateway",
  "retryable": false
}}

Коды включают invalid_input, unknown_account, not_found, too_large, batch_too_large, rate_limited, forbidden_operation, forbidden_label, account_read_only, needs_reauth, upstream_rate_limited, upstream_unavailable, network_error, timeout и internal_error. Внутренние исключения регистрируются на стороне сервера и сообщаются как простое internal_error — клиенты никогда не получают трассировку стека или внутренний путь.

Администрирование

gmail-mcp-gateway accounts list
gmail-mcp-gateway accounts status               # live Gmail check per account
gmail-mcp-gateway accounts auth <alias>
gmail-mcp-gateway accounts reauth <alias>       # after a revoked or expired grant
gmail-mcp-gateway accounts remove <alias> --yes # revokes at Google, deletes locally

gmail-mcp-gateway token create <name>
gmail-mcp-gateway token list
gmail-mcp-gateway token revoke <name>

gmail-mcp-gateway audit --limit 50              # recent state-changing operations
gmail-mcp-gateway audit --account work --since-hours 24
gmail-mcp-gateway audit --outcome denied --json

gmail-mcp-gateway prune                         # expired audit rows, dedup keys, attachments
gmail-mcp-gateway health --json

На безголовом хосте авторизуйтесь с перенаправлением порта редиректа:

# on the server
gmail-mcp-gateway accounts add work --no-browser --port 8899
# on your laptop
ssh -L 8899:127.0.0.1:8899 server
# then open the printed URL locally

Журнал аудита записывает учетную запись, метку времени, операцию, затронутые идентификаторы, результат, код ошибки, продолжительность и вызывающего участника — как для успехов, так и для отказов и отказов в доступе. Он никогда не записывает токены, тела сообщений, темы или содержимое вложений. Администрирование только через CLI: скомпрометированный MCP-клиент не может добавить учетную запись, запустить поток согласия, выпустить токен или прочитать журнал аудита.

Структура каталогов

Конфигурация, данные и секреты разделены и могут переопределяться отдельно, поэтому каждый может иметь свое хранилище:

config.toml необязателен; см. deploy/config.example.toml для всех ключей — лимиты пакетов, размеры страниц, бюджеты тела и вложений, ограничения скорости, политика повторных попыток и окно идемпотентности — со значениями по умолчанию.

Как обеспечивается граница безопасности

Четыре независимых уровня. Каждый по отдельности заблокирует отправку; все четыре должны отказать, чтобы сообщение было отправлено.

1. Поверхность инструментов. Существует восемнадцать инструментов. Нет gmail_send, нет gmail_trash, нет gmail_raw_request и нет инструмента, который принимает URL, путь, HTTP-метод или имя конечной точки. Универсальный прокси Gmail недоступен клиенту, потому что он не был написан. mcpsrv/server.py

2. Белый список конечных точек. Каждый HTTP-запрос к Gmail должен указывать одну из четырнадцати констант Endpoint. users.messages.send, users.drafts.send, users.messages.trash, users.messages.delete и все, что находится под users.settings, просто отсутствуют. Параметры пути проверяются на соответствие строгому шаблону идентификатора и кодируются в процентах с пустым набором безопасных символов, поэтому ни одно значение не может ввести / и достичь другой конечной точки. Черный список повторно проверяет разрешенный метод и путь непосредственно перед отправкой запроса, независимо от того, как он был построен. DELETE и PATCH не могут быть выданы вообще. gmail/allowlist.py

3. Политика меток. Это закрывает черный ход, оставленный белым списком. users.messages.modify разрешен — он нужен для архивирования и состояния прочтения — но Gmail рассматривает TRASH и SPAM как обычные метки, поэтому применение одной из них помещает сообщение в корзину или помечает как спам. Каждый идентификатор метки в мутации проверяется в обоих направлениях, без учета регистра, и собранное тело запроса проверяется снова перед отправкой. gmail/labels.py

4. Область OAuth. Учетные записи авторизованы с gmail.modify и ничем другим. Эта область не может навсегда удалить сообщение (messages.delete требует https://mail.google.com/) и не может касаться никаких настроек Gmail, поэтому правила пересылки, фильтры, конфигурация POP/IMAP и безвозвратное удаление невозможны на уровне авторизации Google, а не просто заблокированы здесь. Google не публикует область, предоставляющую создание черновика без отправки, поэтому отправка блокируется уровнями 1–2. Учетные записи, добавленные с --read-only, получают gmail.readonly, и сам Google затем отклоняет любую запись.

Модель безопасности

Содержимое электронной почты не заслуживает доверия. Тела писем, темы, имена отправителей и имена файлов вложений написаны третьими лицами и могут содержать инструкции, предназначенные для читающей их модели. Шлюз помечает каждый результат чтения content_is_untrusted: true, а инструкции сервера сообщают клиенту обрабатывать электронную почту как данные, а не как указания. Что более полезно, возможности, которые запросили бы внедренные инструкции, не существуют.

HTML никогда не выполняется и не возвращается как разметка. <script>, <style>, <iframe> и подобные элементы отбрасываются вместе с их содержимым; все остальные теги удаляются. Результат — обычный текст.

Невидимые символы Unicode удаляются. Символы нулевой ширины, переопределения двунаправленности и теговые символы Unicode позволяют злоумышленнику показать человеку одно, а LLM прочитать другое. Они удаляются, и количество сообщается как removed_hidden_characters.

Вложения хранятся, никогда не открываются. Шлюз не анализирует, не отображает и не выполняет содержимое вложений. Клиент может предложить имя файла, но никогда не путь: назначение всегда <attachments_dir>/<account>/<message_id>/<sanitized-name>, разрешенное и повторно проверенное на изоляцию, записанное с O_NOFOLLOW в режиме 0600.

Учетные данные никогда не достигают клиента. Токены обновления, токены доступа и секрет клиента OAuth существуют только внутри процесса шлюза. Учетные данные каждой учетной записи запечатаны с помощью AES-256-GCM с ключом, полученным для каждой учетной записи (HKDF-SHA256(master, "…account:<id>")), с идентификатором учетной записи в качестве связанных данных — поэтому ключ одной учетной записи не открывает другую, и файл учетных данных, перемещенный между учетными записями, не расшифровывается. Файлы имеют режим 0600 в каталоге 0700; шлюз отказывается читать ключ, доступный для чтения группой или всеми.

Честная область: шифрование в состоянии покоя защищает от резервных копий, случайных копий и образов дисков. Оно не защищает от злоумышленника, уже выполняющего код от имени пользователя шлюза — этот злоумышленник может прочитать мастер-ключ. Разрешения файловой системы остаются основной границей.

Журналы не могут раскрыть секреты. Каждая запись журнала проходит через фильтр редактирования, который перезаписывает все, что похоже на токен доступа или обновления Google, секрет клиента, заголовок bearer, JWT или поле, названное как учетные данные — в сообщении, аргументах и тексте исключения. При stdio журналы отправляются в stderr, потому что stdout — это провод MCP.

Входные данные проверяются. Получатели черновика должны быть голыми адресами, соответствующими строгому шаблону; любой CR, LF или NUL в значении заголовка отклоняется как попытка внедрения заголовка. Черновики собираются из типизированных полей — шлюз никогда не принимает необработанный RFC 5322 от клиента. Пакеты, размеры страниц, длины тела, размеры вложений и количество получателей ограничены, а ведро токенов для каждой учетной записи быстро завершается ошибкой с подсказкой retry_after_seconds, а не ставит в очередь.

От чего это не защищает

• Оператор, который может выполнять код от имени пользователя шлюза.

• Клиент, законно использующий разрешенные возможности во вред — массовое архивирование, например, или написание вводящего в заблуждение черновика. Архивирование и маркировка обратимы и аудируются; черновики все равно требуют отправки человеком.

• Компрометация со стороны Google или вредоносная конфигурация клиента OAuth.

• Перехват трафика, если вы предоставляете HTTP-транспорт без TLS. Держите его на loopback или поставьте перед ним прокси с завершением TLS.

Надежность

• Обновление токена: автоматическое, с блокировкой для каждой учетной записи, чтобы параллельные вызовы обновлялись один раз. 401 запускает ровно одно обновление и повторную попытку.

• Сбой обновления: invalid_grant помечает учетную запись как needs_reauth и возвращает структурированную ошибку с указанием команды CLI для ее исправления.

• Ограничения скорости и 5xx: экспоненциальная задержка с полным джиттером, с учетом Retry-After, до max_attempts.

• Сбои сети и тайм-ауты: повторяются, затем сообщаются как network_error или timeout без внутренних деталей.

• Пагинация: next_page_token возвращается клиенту, поэтому состояние курсора не хранится на сервере.

• Дублирующиеся запросы: client_request_id подавляет повторы в течение 24 часов. Одновременные повторы сериализуются внутри процесса; повторное использование идентификатора с другими аргументами является ошибкой, а не молчаливым неверным ответом.

• Обратное давление: вызовы Gmail используют настраиваемый семафор параллелизма, и каждая учетная запись имеет независимое ведро токенов. Поэтому большой поиск или занятая учетная запись не могут создать неограниченный восходящий параллелизм.

Топология масштабирования и развертывания

Запустите один процесс шлюза для данного каталога данных и секретов. Состояние SQLite, файлы учетных данных, блокировки обновления токенов и координация идемпотентности в процессе намеренно локальны; указание нескольких реплик на один и тот же том не обеспечивает безопасную активную-активную работу.

Для более крупной установки разделите учетные записи по независимым экземплярам шлюза, каждый со своей конфигурацией, данными, секретами, токенами bearer и портом loopback. Это изолирует сбои, ограничения скорости, цепочки аудита и учетные данные, позволяя при этом каждому экземпляру обслуживать параллельных клиентов. Увеличивайте limits.max_concurrency только после наблюдения за использованием квоты Gmail и емкостью хоста; значение по умолчанию 8 является консервативным. Поместите перед ним уровень маршрутизации с аутентификацией TLS, если клиентам нужен один общий сетевой адрес, и направляйте каждый псевдоним учетной записи на свой экземпляр.

Активные-активные реплики для одной и той же учетной записи потребовали бы замены SQLite и локального состояния учетных данных/идемпотентности на координированные внешние хранилища. Это выходит за рамки текущей модели безопасности шлюза; не масштабируйте его, просто добавляя рабочие процессы или разделяя его том.

Тестирование

uv sync --all-extras
uv run pytest -q                                    # 334 tests, no Google account needed
uv run pytest tests/test_security_boundary.py -v    # just the guarantee

test_security_boundary.py проводит каждую поддерживаемую операцию через фиктивный Gmail, который завершается ошибкой, если запрашивается запрещенный URL, затем пытается отправить в корзину, спам и отправить по всем доступным маршрутам.

После авторизации учетной записи протестируйте ее на реальном почтовом ящике. Скрипт подключается через stdio точно так же, как MCP-клиент, выполняет ознакомительный тур только для чтения, затем подтверждает, что запрещенные операции отклонены:

uv run python scripts/try-it.py --account personal
uv run python scripts/try-it.py --account personal --draft    # also drafts a reply
uv run python scripts/try-it.py --account personal --archive  # archive round trip

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

Для интерактивного взаимодействия:

npx @modelcontextprotocol/inspector .venv/bin/gmail-mcp-gateway serve --transport stdio

Структура

src/gmail_mcp_gateway/
├── mcpsrv/server.py      the tool surface — the complete client-facing API
├── mcpsrv/http.py        Streamable HTTP transport, bearer auth, bind safety
├── service.py            the supported operations, and nothing else
├── gmail/allowlist.py    the endpoint allowlist  ← security boundary
├── gmail/labels.py       label policy (blocks TRASH/SPAM)  ← security boundary
├── gmail/client.py       the only code that talks to Gmail
├── gmail/parse.py        MIME → structured data, sanitization
├── gmail/compose.py      draft assembly from typed fields
├── security/             validation, rate limiting, path confinement
├── auth/oauth.py         OAuth 2.0 + PKCE, refresh, revoke
├── accounts.py           account registry
├── crypto.py             envelope encryption for credentials
├── audit.py              audit log
└── cli.py                administration

Добавление поддерживаемой операции означает: Endpoint в allowlist.py, метод в service.py, инструмент в mcpsrv/server.py, запись в EXPOSED_TOOLS и тесты. EXPOSED_TOOLS и FORBIDDEN_TOOLS проверяются на работающем сервере, поэтому добавление инструмента без его объявления — или добавление запрещенного — приводит к сбою набора. Держите шлюз сфокусированным на Gmail; другой продукт Google относится к отдельному MCP-сервису, а не к более широким областям здесь.

Устранение неполадок

no OAuth client configured — шаг 3 быстрого старта. Поместите secrets/oauth_client.json (режим 0600) или установите GMAIL_MCP_OAUTH_CLIENT_ID и GMAIL_MCP_OAUTH_CLIENT_SECRET.

Google did not return a refresh token — вы уже авторизовали это приложение. Удалите его доступ на https://myaccount.google.com/permissions и снова запустите accounts auth <alias>.

consent screen did not grant every required permission — флажок разрешения не был установлен. Повторите авторизацию и оставьте все флажки установленными. Шлюз намеренно завершается здесь ошибкой, а не оставляет учетную запись, которая работает наполовину.

Учетная запись переходит в needs_reauth каждую неделю — приложение OAuth все еще находится в режиме "Тестирование", где Google аннулирует токены обновления через 7 дней. Опубликуйте его (шаг 2.4 быстрого старта).

stored credential failed authentication — GMAIL_MCP_MASTER_KEY изменился или файл ключа был заменен. Восстановите исходный ключ или выполните accounts reauth <alias> для каждой учетной записи.

<file> is accessible to other users — шлюз отказывается читать секрет, доступный для чтения группой или всеми. Выполните chmod 600 для указанного файла.

refusing to bind …: it is not a loopback address — ожидаемо. Привяжитесь к 127.0.0.1 и используйте SSH-туннель или установите GMAIL_MCP_ALLOW_REMOTE_BIND=true, если это действительно доверенный частный интерфейс. Адреса, маршрутизируемые через Интернет, отклоняются в любом случае.

serve --transport stdio выглядит зависшим — правильно; он ожидает JSON-RPC на stdin. Позвольте вашему MCP-клиенту запустить его или используйте scripts/try-it.py.

Кто-то изменил почтовый ящик, и я хочу узнать, что именно — gmail-mcp-gateway audit --limit 50. Все изменения состояния там, включая отказы.

Лицензия

MIT