gmail-mcp

Gmail для вашего ИИ-ассистента — несколько аккаунтов одновременно, на вашем собственном сервере.

日本語版 · 简体中文

gmail-mcp подключает Gmail к Claude и любому другому MCP клиенту. Он умеет искать и читать письма, отправлять и отвечать всем с цитируемой историей, пересылать, работать с вложениями и встроенными изображениями, а также управлять черновиками, метками и ветками — сразу в нескольких аккаунтах Google.

Он работает как удалённый сервер на вашем собственном Cloudflare Worker, поэтому одно и то же соединение отвечает из Claude Code на ноутбуке, claude.ai в браузере и Claude на телефоне. Каждое соединение входит в один аккаунт Google, а Google refresh-токен остаётся в вашем аккаунте Cloudflare.

Сюда людей приводят две вещи. Встроенные в Claude и Google коннекторы Gmail читают почту и создают черновики, но не могут отправлять письма и привязывают один аккаунт Google к одному аккаунту ассистента. Серверы, которые умеют отправлять, обычно являются локальными процессами — хороши за рабочим столом, но недоступны с телефона.

Сравнение

google_workspace_mcp — самый полный проект здесь. Он охватывает весь Workspace, а не только Gmail, добавляет вашу подпись Gmail и загружает вложения прямо по URL — ни того, ни другого gmail-mcp не делает. shinzo-labs/gmail-mcp через свои 64 инструмента добирается до автоответчиков, делегированных аккаунтов и S/MIME; они живут в gmail.settings.* — области, которую gmail-mcp никогда не запрашивает, так что они остаются вне его досягаемости, что бы ни случилось с разрешением.

Два различия в архитектуре определяют почти всё остальное. Маршрутизация аккаунтов по аргументу вызова позволяет одному разрешению касаться каждого подключённого почтового ящика, тогда как привязка ящика к соединению означает, что неверный аргумент не достигает ничего. А при чтении локальные серверы декодируют каждую часть как UTF-8: письма в ISO-2022-JP и Shift_JIS приходят с искажениями, а длинные сообщения, которые Gmail хранит в виде блобов-вложений, возвращаются с пустым телом.

Развёртывание

Примерно десять минут. Вам понадобятся аккаунт Cloudflare, bun и аккаунт Google. Домен в аккаунте Cloudflare необязателен — без него Worker отвечает на workers.dev.

1 · Создайте Google OAuth-клиент

PROJECT="gmail-mcp-$(openssl rand -hex 3)"
gcloud auth login
gcloud projects create "$PROJECT" --name="gmail-mcp"
gcloud config set project "$PROJECT"
gcloud services enable gmail.googleapis.com

Google не предоставляет API для следующих двух шагов, поэтому они выполняются в Cloud console:

• Экран согласия OAuth → External, затем в разделе Audience нажмите Publish app. Если оставить статус Testing, Google истекает срок действия каждого refresh-токена через 7 дней, и каждое подключение умирает вместе со своим токеном. После публикации приложение показывает предупреждение о непроверенном приложении при входе и обслуживает до 100 аккаунтов.

• Credentials → Create credentials → OAuth client ID → Web application, с https://<your-host>/callback в качестве авторизованного URI перенаправления. Сохраните client ID и секрет.

<your-host> — это домен, который вы указываете для Worker, или имя хоста workers.dev, которое он получает в противном случае. Можно сначала развернуть, а потом вернуться и заполнить это — руководство, которое Worker отдаёт по адресу /, показывает точное значение.

2 · Разверните Worker

Кнопка копирует репозиторий в ваш аккаунт GitHub, создаёт пространство имён KV и Durable Object и запрашивает четыре секрета. Развёртывание происходит на workers.dev; пользовательский домен подключается позже через Settings → Domains & Routes.

Вместо этого из терминала:

git clone https://github.com/mkpoli/gmail-mcp && cd gmail-mcp
bun install
bun run setup

bun run setup спрашивает, на каком домене отвечать, создаёт или переиспользует пространство имён OAUTH_KV, принимает client ID и секрет, генерирует ключ cookie и развёртывает. Первые два ответа попадают в wrangler.local.jsonc, который git игнорирует — wrangler.jsonc не называет ни пространство имён какого-либо аккаунта, ни чей-либо домен, поэтому клон развёртывается где угодно. Повторный запуск setup для ротации одного секрета безопасен.

3 · Подключите клиент

Оставьте поля client ID и секрета пустыми — MCP-клиенты регистрируются сами.

claude mcp add --transport http gmail-personal https://<your-host>/mcp
claude mcp add --transport http gmail-work     https://<your-host>/mcp/work

Запустите /mcp в Claude Code, чтобы подписать каждое подключение на свой аккаунт Google. В claude.ai это Settings → Connectors → Add custom connector с тем же URL. Любая метка из одного сегмента работает после /mcp/ — так одно развёртывание обслуживает несколько почтовых ящиков для клиентов, которые не принимают два сервера с общим URL.

Ваше развёртывание отдаёт это руководство по адресу https://<your-host>/.

Что умеет

whoami search_messages get_message get_thread get_attachment

send_message reply_all forward_message create_draft update_draft send_draft delete_draft list_drafts stage_attachment_begin stage_attachment_append stage_attachment_finish

list_labels create_label update_label delete_label modify_labels modify_thread_labels batch_modify_messages trash_message · untrash_message trash_thread · untrash_thread

Письма отправляются так, как их отправляет почтовый клиент: обычный текст с HTML-альтернативой, файловые вложения и встроенные изображения, на которые ссылаются через cid:, вложенные как multipart/mixed › multipart/related › multipart/alternative. Темы и отображаемые имена используют RFC 2047, имена файлов — RFC 2231, поэтому японский, китайский и эмодзи переживают путь без потерь.

reply_all читает Reply-To, From, To и Cc исходного письма, отбрасывает ваш собственный адрес и любой адрес, с которого вы отправляете почту, отвечает с того адреса, на который писал отправитель, переносит цепочку References и цитирует оригинал в тех частях, которые вы отправляете. forward_message воспроизводит пересылаемый конверт и может повторно прикрепить файлы оригинала.

create_draft с replyToMessageId записывает ответ как черновик для редактирования перед отправкой: он присоединяется к ветке оригинала, переносит In-Reply-To и References, вычисляет получателей ответа всем и тему Re: и цитирует оригинал. update_draft изменяет только те поля, которые ему переданы; получатели, текст, файлы, добавленные вручную в любом клиенте, и ветка, на которую отвечает черновик, считываются обратно и сохраняются. Файл, чей base64 не помещается в аргументы инструмента, вместо этого разбивается на этапы: stage_attachment_begin возвращает URL для загрузки, который принимает сырые байты одним curl -T, stage_attachment_append принимает base64 частями, и каждое поле attachments принимает полученный stagingId.

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

Как это работает

Два потока OAuth встречаются в одном Worker. MCP-клиент аутентифицируется у Worker; Worker аутентифицируется у Google от вашего имени. Ни одна сторона не хранит учётные данные другой.

sequenceDiagram
    autonumber
    participant C as MCP client<br/>(Claude Code · claude.ai)
    participant W as Worker<br/>(OAuthProvider + McpAgent)
    participant G as Google<br/>(OAuth + Gmail API)

    C->>W: POST /register (dynamic client registration)
    C->>W: GET /authorize (PKCE challenge)
    W->>C: approval dialog
    C->>G: consent screen — pick the account
    G->>W: GET /callback?code=…
    W->>W: allowlist check on the verified email
    W->>G: exchange code → access + refresh token
    W->>C: MCP access token (Google tokens sealed inside the grant)
    C->>W: POST /mcp — tools/call
    W->>G: Gmail REST (token refreshed as needed)
    G->>W: message / thread / label data
    W->>C: tool result

Создано с помощью

• TypeScript на Cloudflare Workers — Durable Objects держат по одной MCP-сессии, KV хранит OAuth-гранты

• Hono — маршрутизация для OAuth-эндпоинтов, колбэка Google и страницы настройки по адресу /

• @cloudflare/workers-oauth-provider — сервер OAuth 2.1, против которого регистрируются MCP-клиенты

• agents — McpAgent, MCP-транспорт поверх Durable Objects

• @modelcontextprotocol/sdk с Zod — определения инструментов и валидация аргументов

• Bun, Biome, Wrangler — установка, тесты, линтинг, развёртывание

Сам Gmail вызывается через обычный fetch против REST API. Официальный SDK googleapis предполагает Node и несёт гораздо больше, чем должен поставлять Worker, поэтому построение сообщений, разбор MIME и обновление токенов живут в src/gmail.ts и src/utils.ts вместо этого.

Эндпоинты

Кто может войти

ALLOWED_EMAILS решает, проверяя адрес, который Google сообщает как подтверждённый — после согласия, до создания любого гранта.

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

Лимиты

Два потолка защищают общее развёртывание от истощения, оба задаются в wrangler.jsonc:

На тарифе Workers Free действует дополнительный предел: 50 исходящих запросов на один вызов. Широкое чтение тратит по одному запросу на сообщение, поэтому search_messages и list_drafts там требуют maxResults не выше 45; выше этого излишек возвращается как ошибки на каждое сообщение, а не как результаты. Платный тариф допускает 1000.

Поднимите любой из них и переразверните. Ограничитель скорости Cloudflare считывает свой потолок из привязки во время сборки, так что simple.limit на каждом из них — единственное место, где это меняется. Развёртывание для одного пользователя может оставить оба значения без изменений — обычное использование ассистента находится далеко ниже них.

Безопасность

Самостоятельный хостинг перемещает вопрос доверия, а не устраняет его, поэтому вот где всё находится.

• Ваши токены остаются вашими. Refresh-токены зашифрованы внутри их OAuth-гранта в вашем пространстве имён KV. Durable Object сессии хранит часовой access-токен, а MCP-агентный фреймворк держит копию гранта там, пока жив объект, включая refresh-токен. Оба хранилища — ваш собственный аккаунт Cloudflare, зашифрованный в состоянии покоя. Почта никогда не хранится — она проходит насквозь.

• Одна сессия — один почтовый ящик. MCP-сессия привязана к аккаунту, который её открыл, поэтому грант для одного ящика не может действовать на другой через заимствованный идентификатор сессии.

• Минимализм областей доступа. gmail.modify покрывает чтение, отправку, метки и корзину. Он исключает окончательное удаление и все gmail.settings.*, не позволяя правилам авто-пересылки и фильтрам-эксфильтрациям — классическим бэкдорам почтового ящика — выйти за пределы того, что может сделать украденный грант. Рядом с ним запрашиваются два read-only скоупа, userinfo.email и userinfo.profile: именно они позволяют allowlist и привязке сессии знать, какой аккаунт вошёл, и они не касаются почты.

• Заголовки нельзя протащить. Каждое исходящее значение заголовка отклоняется, если содержит CR, LF или NUL, так что ни один аргумент не может вырваться из своего поля, чтобы добавить другое — например, Bcc внутри темы письма. Типы медиа проверяются, а цитируемая история экранируется как HTML. Это не контролирует сами аргументы: bcc — реальный параметр, поэтому модель, действующая по инструкции, скрытой в теле сообщения, всё ещё может его заполнить, и ваш запрос на подтверждение в клиенте остаётся проверкой этого.

• Доступ можно отозвать. Сужение ALLOWED_EMAILS останавливает новые входы. Доступ одного аккаунта отзывается на myaccount.google.com/connections. Ротация секрета клиента Google аннулирует все гранты сразу.

Worker расшифровывает почту в памяти, обслуживая запрос, как это должен делать любой хостируемый ретранслятор. Если это неприемлемо для конкретного ящика, запустите локальный MCP-сервер для него.

Как это тестировалось

253 юнит-теста покрывают построение сообщений (вложенность MIME, переносы RFC 2047, имена файлов RFC 2231, отклонение CR/LF, перенос base64), извлечение тела в разных кодировках, составление ответов и пересылок, потоки токенов Google, allowlist входа, проверки CSRF и привязки состояния, защищающие браузерную сторону входа, и сами инструменты против подставного Gmail — владение сессией, составление получателей, выбор вложений и то, что возвращает частично неудачное чтение.

Кроме того, каждый инструмент запускался против реальных аккаунтов Gmail, а отдельный аккаунт проверял, что пришло:

Разработка

bun run dev     # wrangler dev on :8788
bun run check   # biome + tsc
bun test        # 253 unit tests
bun run assets  # regenerate the light and dark diagrams
bun run deploy

Вопросы и ошибки

Откройте issue.

Лицензия

Copyright © 2026 mkpoli. Выпущено под лицензией MIT.

src/workers-oauth-utils.ts является производным от remote-mcp-github-oauth demo в cloudflare/ai, Copyright © 2025 Cloudflare, Inc., используется под лицензией MIT. См. THIRD-PARTY.md.