gmail-mcp

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

日本語版 · 简体中文

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

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

Related MCP server: Gmail MCP Server

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

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

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

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 → Внешний, затем в разделе Аудитория нажмите Опубликовать приложение. Если оставить в статусе «Тестирование», Google аннулирует каждый токен обновления через 7 дней, и каждое соединение прекращает работу вместе с токеном. Если опубликовать, приложение будет показывать предупреждение о непроверенном приложении при входе и обслуживать до 100 аккаунтов.

• Учетные данные → Создать учетные данные → Идентификатор клиента OAuth → Веб-приложение, с https://<your-host>/callback в качестве разрешенного URI перенаправления. Сохраните идентификатор клиента и секрет.

<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, принимает идентификатор клиента и секрет, генерирует ключ cookie и развертывает. Первые два ответа попадают в wrangler.local.jsonc, который игнорируется git — wrangler.jsonc не указывает ни пространство имен учетной записи, ни чей-либо домен, поэтому клон развертывается где угодно. Повторный запуск setup для ротации одного секрета безопасен.

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

Оставьте поля идентификатора клиента и секрета пустыми — клиенты 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:

Ссылки

• Репозиторий GitHub

• Обсуждения

• Проблемы

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

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

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

Самостоятельное размещение не устраняет проблему доверия, а лишь перемещает её, поэтому вот как обстоят дела.

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

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

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

• Заголовки невозможно подделать. Каждое исходящее значение заголовка отклоняется, если содержит 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, белый список входа, проверки 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 из cloudflare/ai, Copyright © 2025 Cloudflare, Inc., используется по лицензии MIT. См. THIRD-PARTY.md.