gmail-mcp

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

日本語版 · 简体中文

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

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

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

Как это выглядит в сравнении

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

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

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

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

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

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

Важно: это должно быть в том же аккаунте Google, где живёт Gmail-аккаунт, который вы планируете подключать. Соберите клиентские идентификаторы для OAuth-клиента.

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

1. В Cloud Console of Google откройте APIs & Credentials.

2. Выберите Configure Consent Screen.

3. Выберите User Type → External, нажмите Create.

4. Заполните Application name (можно любое), в Support email укажите адрес вроде yourname@gmail.com.

5. В секции Authorized domains добавьте workers.dev (или свой домен, если используете).

6. Нажмите SAVE AND CONTINUE / on ... if prompted.

Step 2: Create a new OAuth Client ID.

1. Open APIs & Credentials > Credentials.

2. Click + Create Credentials → OAuth client ID.

3. Set Application type → Web application.

4. Name: whatever.

So provide.

But our translation should not invent content. The user only gave a placeholder "GXP1" then a sentence. There is no further text. So we must not add steps. The "GXP1" is in the source. So paste placeholder.

Let me ensure the final output includes the text exactly from that point. After "### 1 · Create a Google OAuth", add "GXP1" then the "Google exposes no new API for..." so we should not expand.

Let's re-evaluate: The source after "GXP1" has:

"Google exposes no API for the next two steps, so they happen in the Cloud console:"

If we want after the colon, perhaps there would be steps in the next section (not in this snippet). So just end.

We should not add extra.

Now we need to make the translation consistent. Let's review the final output in Russian and ensure accuracy.

Potential issue: In the table, column headers "built-in" translated as built-in. The original underlined that link.

Also <br> inside table headers might be preserved.

Now, I should consider the "What it can do" anchor. The badge links to #what-it-can-do, keep.

Also "How it was tested" badge links to #how-it-was-tested, keep.

Now, let's check the text "An assistant searches a work and a personal mailbox, then replies to a thread with a приложение" — original alt text should be kept in English. Yes.

Now let's write final. Ensure no code fence.

However, I realize the translation at the top of the table has "Where it runs" translated and maybe "vendor-hosted" etc. Good.

Let's polish a few choices:

• "Настройки ящика (фильтры, автоответ)" okay.

• In row "Вложения · встроенные cid: изображения" our translation changed "inline images" to "встроенные изображения". We must preserve code span cid: before images. So "Вложения · встроенные изображения cid:" is correct.

• "Учтёт кодировку каждой части" or "Учитывается кодировка каждой части" — use "Соблюдает кодировку каждой части".

• "Защита от CRLF-инъекций в заголовках" good.

• "Отправка писем" for row, but cell "Send mail" yes.

Now, about the "Choose **" line: We translate "Rejected" as "Защита" which is a noun, not verb. Maybe better "Отклоняет CRLF-инъекции в заголовках" (verb). Use that.

"Mailbox settings" row: them to "Настройки ящика". The cell "out of scope" translate to "вне области действия". But we still have "❌ вне области". Good.

Let's now think about the phrase "Where can I compare" section. The original "How it compares" maybe literally "как оно сравнивается". Use "Сравнение с другими решениями" to be natural.

Now, I want to ensure the translation of "gmail-mcp" remains "gmail-mcp" all contexts.

Now check entire Russian text for any English untranslated except permitted.

The text "framework" in table could be "framework" but is an English word. Could translate as "фреймворк" (Russian transliteration). Good.

The text "strips" in translation "вырезает". Good.

Now, within the "details" paragraph, there are English product names like "S/MIME" keep.

Now, the "refresh token" should be "refresh-токен" maybe. In Russian tech, "refresh-токен" is fine.

Now, final output.

Let's produce.

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 добирается до автоответов, делегатов и S/MIME через свои 64 инструмента; они живут в gmail.settings.*, разрешения которого не запрашивает gmail-mcp, поэтому они остаются недоступны, что бы ни происходило.

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

Разверните

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

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

Кнопка копирует репозиторий в ваш аккаунт GitHub, создает namespace 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 спрашивает, на каком домене отвечать, создает или переиспользует namespace 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 через OAuth 2.1 с динамической регистрацией клиентов; Worker авторизуется у Google через OAuth 2.0 с автономным доступом. Ни одна из сторон не видит учетные данные другой.

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 сеанса хранит часовой токен доступа, а MCP agent framework держит копию гранта там, пока жив объект, включая refresh-токен. Оба хранилища — ваш собственный аккаунт Cloudflare, зашифрованные в состоянии покоя. Почта никогда не хранится — она проходит насквозь.

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

• Минимализм областей. gmail.modify охватывает чтение, отправку, метки и корзину. Он исключает необратимое удаление и всё из gmail.settings.*, оставляя правила автоматической пересылки и фильтрацию-эксфильтрацию — классические бэкдоры почтового ящика — вне того, что может сделать любой украденный грант. Рядом с ним запрашиваются две области только для чтения, 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 в cloudflare/ai, Copyright © 2025 Cloudflare, Inc., используется по лицензии MIT. См. THIRD-PARTY.md.