gmail-mcp

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

日本語版 · 简体中文

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

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

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

Сравнение с другими решениями

| | gmail-mcp | Claude · Google встроенные | taylorwilsdon/google_workspace_mcp | ArtyMcLabin/Gmail-MCP-Server | shinzo-labs/gmail-mcp | aaronsb/google-workspace-mcp | | :------------------------------------- | :----------------------: | :---------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------: :-----------------------------------------------------------------------------------: | | Где работает | Cloudflare Workers | размещенный у поставщика | ваш сервер или локально | локально | локально | локально | | Доступность с телефона | possible | ✅ | ✅ | ❌ | ❌ | ❌ | | Несколько ящиков одновременно | ✅ привязано к подключению | ❌ | ✅ выбирается в каждом вызове | ❌ только псевдонимы | ❌ | ✅ выбирается в каждом вызове | | Отправка писем | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | | Вложения · встроенные cid: картинки | ✅ | недокументировано | ✅ | ✅ | ❌ | ✅ | | Ответ-всем с историей переписки | ✅ | ❌ | только черновики | без цитат | ❌ | ✅ | | Пересылка | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | | Учитывает кодировку части | ✅ | — | ❌ жалуется, что UTF-8 | ❌ жалуется на UTF-8 | ❌ | ❌ | | Защита от внедренжей CRLF-заголовков | ✅ | — | ❌ предполагается UTF-8 | ✅ удаляет | ❌ никого | ✅ | | Настройки почты (фильтры, автоответ) | ❌ вне рамок | ❌ | фильтры | фильтры | ✅ | ❌ | | Количество инструментов | 24 | 11–16 | 14 (Gmail) | 30 | 64 | 11 | | Кому принадлежит ваш refresh token | вам | вашему провайдеру | вам | вам | вам | вам |

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 Connector

Как это развер

Около десяти минут. Требуется аккаунт 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:

• Экран согласия 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.*, оставляя правила автоматической пересылки и фильтрацию-эксфильтрацию — классические бэкдоры почтового ящика — вне того, что может сделать украденный грант. Две области только для чтения запрашиваются вместе с ним, 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.