multi-gmail-cowork-mcp

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

Claude Cowork
      |
      v
Your private Multi-Gmail MCP  (your own Cloud Run project)
      |
      +-- Gmail account: "personal"
      +-- Gmail account: "work"
      +-- Gmail account: "billing"
      +-- ...more, added any time via the admin page

Спрашивайте Claude, например:

• «Найди в моей рабочей Gmail письма от Дэвида».

• «Найди во всех подключенных аккаунтах Gmail письма с „invoice 4831“».

• «Прочитай последнее письмо от ACH Works, в каком бы аккаунте оно ни было».

• «Какой из моих аккаунтов Gmail получил вчера письмо от Джона?»

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

Что это не такое

Только Gmail. Никаких Calendar, Drive, Docs, Sheets или Contacts. Никакого инструмента необратимого удаления. Никакого общего бэкенда, центрального аккаунта или телеметрии.

Related MCP server: Gmail MCP

Модель конфиденциальности — кто может видеть вашу электронную почту

Google  <->  Your Google Cloud deployment  <->  Claude / Anthropic

• Вы развертываете это в своем проекте Google Cloud, используя свой OAuth-клиент Google и свой сервис Cloud Run.

• Google выдает/может отозвать OAuth-разрешения; он видит обычный OAuth-трафик.

• Ваше развертывание — единственное место, где когда-либо хранятся refresh-токены Gmail.

• Claude/Anthropic видит то, что возвращают инструменты, когда Claude их вызывает (как и любой другой MCP-инструмент) — не больше, и ничего, когда вы не используете его.

• Автор этого репозитория никогда не видит вашу электронную почту. Нет общего сервера. Развертывание вашего двоюродного брата и ваше развертывание не имеют ничего общего, кроме исходного кода.

Прочтите SECURITY.md для полного описания границ доверия и обоснования дизайна — включая точные причины, по которым аутентификация реализована именно так, и известные ограничения этого проекта. В этом README эти рассуждения не повторяются.

Архитектура вкратце

• Язык/среда выполнения: TypeScript на Node.js 20+, с использованием официального @modelcontextprotocol/sdk и google-auth-library от Google.

• Транспорт: Streamable HTTP (текущий рекомендуемый MCP удаленный транспорт), без сохранения состояния — каждый запрос обрабатывается независимо, поэтому он масштабируется на Cloud Run без необходимости привязки сессий.

• Аутентификация Claude <-> сервер: MCP OAuth 2.1 authorization-code flow с PKCE/S256, Dynamic Client Registration, короткоживущие access-токены, ротация refresh-токенов и состояние авторизации, локальное для развертывания, в Secret Manager.

• Аутентификация сервер <-> Google: стандартный OAuth 2.0 с PKCE, одно разрешение на каждый подключенный аккаунт Gmail, область gmail.modify (чтение, составление, отправка и изменение почтового ящика; без необратимого удаления).

• Хранение аккаунтов: один секрет в Google Secret Manager, содержащий небольшой JSON-массив (псевдоним, email, refresh-токен). Без базы данных.

• Административный интерфейс: несколько неоформленных HTML-страниц за HTTP Basic Auth — достаточно для подключения или отключения аккаунтов.

Предварительные требования

• Учетная запись Google и проект Google Cloud с включенным биллингом (bootstrap выводит точную страницу биллинга, если биллинг не привязан).

• План Claude, поддерживающий пользовательские коннекторы (для подключения к Cowork/claude.ai).

• Больше ничего для развертывания не требуется: Google Cloud Shell уже включает gcloud, curl, openssl и jq.

Стоимость и биллинг

Cloud Run требует проект с включенным биллингом. Это развертывание рассчитано на личное/малый бизнес использование: min instances 0 (масштабируется до нуля в простое) и max instances 3. Обычное использование — несколько поисков, чтений и отправок в день — остается в пределах Always Free лимита Google Cloud для Cloud Run, поэтому реальная текущая стоимость составляет $0. Это не гарантия: устойчивый всплеск запросов сверх бесплатного лимита повлечет обычные расходы Cloud Run. Bootstrap выводит необязательную ссылку на бюджетное оповещение, если вы хотите получить уведомление до любых трат.

Настройка в Cloud Shell одной командой (рекомендуется)

1. Откройте этот репозиторий в Google Cloud Shell с помощью кнопки выше (или используйте Open in Cloud Shell на GitHub).

2. Аутентифицируйтесь, если Cloud Shell попросит, затем выполните:

./scripts/bootstrap.sh

Скрипт попросит вас выбрать проект (или создаст его), проверит биллинг, включит необходимые API, создаст выделенный сервисный аккаунт для Cloud Run, назначит только те роли Secret Manager, которые нужны, создаст все секреты, развернет Cloud Run и выведет проверки PASS/FAIL. Его можно безопасно перезапускать: существующие секреты, записи аккаунтов, OAuth-учетные данные и сервисы Cloud Run сохраняются.

Скрипт никогда не выводит пароль, секрет OAuth-клиента, refresh-токен, JSON хранилища аккаунтов или MCP OAuth-токен. Значения секретов записываются как точные байты (без ошибки с завершающим переводом строки). Используйте ./scripts/bootstrap.sh --check для проверки предварительных требований Cloud Shell в режиме только для чтения.

Единственный неизбежный шаг в браузере Google

Google не предоставляет безопасной поддерживаемой операции API/CLI для создания универсального веб- OAuth-клиента. Когда bootstrap попросит, откройте страницу Google Auth Platform, которую он выведет, и сделайте следующее:

• Настройте приложение как External, добавьте область https://www.googleapis.com/auth/gmail.modify и добавьте адреса Gmail, которые вы будете использовать, как тестовых пользователей.

• Создайте OAuth-клиент с типом приложения Web application.

• Введите точный URI обратного вызова, выведенный скриптом: https://<your-cloud-run-host>/oauth/google/callback.

• Вставьте полученные Client ID и Client Secret в скрытые подсказки в Cloud Shell.

Если Google покажет предупреждение о непроверенном приложении, это ожидаемо для личного развертывания. Опубликуйте экран согласия как In production, если вы хотите, чтобы refresh-токены оставались действительными дольше семидневного лимита Testing-режима; проверка не требуется для личного/малого развертывания.

В конце bootstrap выводит Admin URL, точный URL обратного вызова Google OAuth, MCP URL и следующее действие человека. Claude аутентифицируется на MCP-эндпоинте через поддерживаемый OAuth-поток; нет статического заголовка коннектора, который нужно копировать или вставлять в URL.

Подключение аккаунтов Gmail

1. Получите пароль администратора (сгенерированный bootstrap, никогда не выводимый) с помощью команды, которую bootstrap вывел в конце:

   gcloud secrets versions access latest --secret=admin-password --project=YOUR_PROJECT_ID

   Затем откройте выведенный Admin URL и войдите с именем пользователя admin и этим паролем.

2. Введите короткий псевдоним, например personal или work, нажмите Add Gmail Account и завершите авторизацию Google. URL авторизации запрашивает consent select_account, поэтому Google каждый раз показывает выбор аккаунта. Адрес, отображаемый после обратного вызова, — это адрес, который Google фактически авторизовал; он не берется из поля псевдонима.

3. Повторите для стольких аккаунтов Gmail, сколько нужно. Каждый псевдоним независим, и все результаты приписываются как псевдониму, так и проверенному адресу Gmail.

Подключение Claude Cowork

В Claude откройте Settings → Connectors → Add custom connector и введите точно:

1. Connector name: Multi Gmail

2. Remote MCP URL: выведенный URL, заканчивающийся на /claude-mcp

3. OAuth Client ID: оставьте пустым (сервер поддерживает Dynamic Client Registration)

4. OAuth Client Secret: оставьте пустым

Маршрут /mcp остается доступным для существующих клиентов; используйте /claude-mcp для новых коннекторов Claude, чтобы его OAuth-идентичность ресурса была независима от старых записей коннекторов.

Нажмите Add, затем Connect. Claude обнаружит метаданные авторизации MCP, зарегистрируется и откроет страницу Authorize MCP access вашего развертывания. Войдите там с именем пользователя admin и паролем администратора, хранящимся в вашем собственном секрете admin-password в Secret Manager, затем одобрите. Claude перенаправит через свой обратный вызов на https://claude.ai/api/mcp/auth_callback, сохранит OAuth-токены и переподключится. Не вводите OAuth-клиент ID или секрет Gmail в Claude — они принадлежат только настройке Gmail от Google.

После подключения коннектора попросите Claude вызвать list_accounts, затем выполните поиск по псевдониму для каждого аккаунта и search_all_accounts, чтобы проверить атрибуцию.

Проверка вашего развертывания

scripts/acceptance_test.mjs доказывает, что каждый инструмент работает end-to-end против вашего собственного развертывания — изоляция аккаунтов, отсутствие подстановки при неверном псевдониме, черновики и отправка с подтверждением получения и правильной идентичностью From. Он выполняет полный MCP OAuth-поток как реальный удаленный клиент и никогда не выводит токены:

MCP_BASE_URL=https://your-service.run.app \
  MCP_ADMIN_PASSWORD='...'   # Secret Manager -> admin-password
  node scripts/acceptance_test.mjs

Тест отправки отправляет одно письмо account-A → account-B и одно account-B → account-A, поэтому получатель всегда является аккаунтом, которым вы владеете. Установите SKIP_SEND=1, чтобы пропустить отправки.

Локальная разработка (необязательно)

Только для разработки исходного кода: установите Node.js 20+, выполните npm install, скопируйте .env.example в .env, установите TOKEN_STORE=file и используйте npm run dev. Локальный OAuth Gmail требует отдельного обратного вызова OAuth-клиента, например http://localhost:8080/oauth/google/callback; не используйте повторно и не коммитьте производственные секреты. Пользователи Windows могут использовать scripts/setup.ps1 и scripts/deploy.ps1 вместо bootstrap в Cloud Shell.

Повторная авторизация / отзыв аккаунтов

После обновления с более раннего релиза только для чтения каждый существующий аккаунт помечается как Needs Gmail permission upgrade. Откройте /admin, нажмите Reauthorize для того же псевдонима и завершите экран согласия Google. Обратный вызов проверяет, что Google действительно предоставил https://www.googleapis.com/auth/gmail.modify, прежде чем заменить сохраненный refresh-токен этого псевдонима. До этого момента инструменты чтения продолжают работать со старым разрешением, а инструменты записи возвращают четкое сообщение о необходимости повторной авторизации; никакой другой псевдоним никогда не используется.

Чтобы удалить доступ, нажмите Disconnect рядом с аккаунтом. Это отзывает разрешение у Google (best-effort) и немедленно удаляет его из хранилища учетных данных — Claude получит четкую ошибку «не подключен», если его попросят об этом псевдониме впоследствии, и никогда не будет молчаливой подстановки.

Чтобы повторно подключить тот же псевдоним после отзыва доступа на стороне Google, используйте Connect account с тем же псевдонимом — он перезапишет старую запись только после успешной авторизации Google.

Инструменты записи и безопасность

Развернутый сервер предоставляет create_draft и send_email. Оба требуют явного псевдонима подключенного аккаунта и никогда не переключаются на другой аккаунт. send_email всегда отправляет с выбранной идентичности Gmail; результат включает этот проверенный адрес. Инструменты используют gmail.modify, а не более широкую область mail.google.com, и нет инструмента необратимого удаления. Разрешения коннектора Claude должны автоматически разрешать инструменты чтения, оставляя create_draft и send_email на Needs approval.

Обновление и ротация

• Обновление развертывания после изменения исходного кода или для получения новой версии секрета: повторно выполните ./scripts/bootstrap.sh (идемпотентно — сохраняет аккаунты, токены и OAuth-клиент) или, на Windows, scripts/deploy.ps1. Существующие подключения Gmail и коннектор Claude не затрагиваются.

• Ротация пароля администратора: добавьте новую версию секрета для admin-password в Secret Manager и переразверните. Существующие токены коннектора Claude остаются действительными (они не производны от пароля администратора); только будущие одобрения MCP-согласия используют новый пароль.

• Ротация oauth-state-secret: этот секрет подписывает каждый MCP OAuth-токен, поэтому его ротация аннулирует существующие токены коннектора Claude — после этого переподключите Claude. Ожидающие токены состояния привязки Gmail (время жизни 10 минут) также аннулируются; подключенные аккаунты Gmail не затрагиваются.

• Ротация разрешения аккаунта Gmail: переподключите псевдоним со страницы администратора (см. Reauthorizing / revoking accounts).

Как удалить все

• Удалите доступ к Gmail: отключите каждую учетную запись через /admin или отзовите доступ напрямую на https://myaccount.google.com/permissions.

• Удалите развертывание:

  gcloud run services delete multi-gmail-mcp --region us-central1
  gcloud secrets delete mcp-oauth-state admin-password oauth-state-secret google-client-id google-client-secret gmail-mcp-accounts
  gcloud iam service-accounts delete multi-gmail-mcp-run@YOUR_PROJECT_ID.iam.gserviceaccount.com

• Удалите OAuth-клиент: Cloud Console -> APIs & Services -> Credentials -> удалите идентификатор OAuth-клиента и при желании удалите конфигурацию экрана согласия OAuth.

• Или проще всего: удалите весь проект Google Cloud.

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

• Ошибки «Account needs to be reconnected»: сохраненный refresh token был отклонен Google (отозван, истек или экран согласия застрял в статусе «Testing» — см. ниже). Переподключите его через /admin.

• Refresh token'ы продолжают умирать через ~7 дней: ваш экран согласия OAuth все еще находится в статусе публикации «Testing». Опубликуйте его как «In production» (см. шаг 3) — он может оставаться непроверенным, для личного использования это нормально.

• Claude не может подключиться к коннектору / подключение молча не удается: убедитесь, что URL службы разрешается по обычному HTTPS без перенаправления на другой хост, затем откройте MCP URL, заканчивающийся на /claude-mcp, в Claude и снова нажмите Connect. Сервер должен возвращать метаданные OAuth и запрос 401 при вызове без access token; статический заголовок запроса не требуется.

• gcloud run deploy не работает, если API не включены: повторно запустите scripts/setup.ps1 или выполните gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com gmail.googleapis.com iam.googleapis.com.

• Локальная разработка не может связаться с Google по HTTPS (ошибки сертификатов): это почти всегда проблема локальной машины (корпоративный прокси или антивирус, перехватывающий TLS), а не ошибка в этом проекте — проверьте доверенные корневые сертификаты вашей машины.

Google OAuth Testing и долгосрочное использование

OAuth-клиенты Google Cloud начинают со статуса публикации Testing. Пока статус Testing, refresh token'ы для чувствительных/ограниченных областей (включая gmail.modify) истекают через 7 дней, независимо от того, сколько у вас пользователей — это будет молча ломать коннектор еженедельно, если оставить как есть.

Решение — не проверка Google (многомесячный процесс, предназначенный для публичных SaaS). Оно проще: нажмите Publish app, чтобы перевести экран согласия в статус In production. Для приложения, запрашивающего только gmail.modify и не превышающего 100 подключенных учетных записей Google, документация Google рассматривает это как полностью поддерживаемый случай личного/маломасштабного использования — проверка не требуется. Единственный видимый эффект — каждая вновь подключенная учетная запись видит одноразовое предупреждение «Google hasn't verified this app», которое нужно просто пропустить, прежде чем предоставить согласие. Это предупреждение ожидаемо; оно не означает, что что-то настроено неправильно. См. SECURITY.md с основными правилами и источниками.

Структура репозитория

src/            TypeScript source (server, MCP tools, admin/setup UI, OAuth flows)
scripts/        bootstrap.sh (Cloud Shell), setup.ps1/deploy.ps1 (Windows),
                acceptance_test.mjs (verify any deployment end-to-end)
.env.example    Local-dev configuration template (placeholders only)
SECURITY.md     Trust model, design rationale, known limitations

Лицензия

MIT — см. LICENSE.