gmail-multi-mcp-server

MCP-сервер, который подключает Claude сразу к нескольким аккаунтам Gmail и предоставляет тот же набор инструментов, что и встроенный коннектор Gmail. Каждый инструмент принимает дополнительный аргумент account, указывающий, с каким почтовым ящиком работать, — это единственное структурное отличие от коннектора для одного почтового ящика.

"Check my work inbox for anything from the lender, and draft the reply from my personal account."

Зачем это нужно

Встроенный коннектор Gmail авторизует один почтовый ящик. Если у вас несколько отдельных аккаунтов — рабочий, личный, корпоративный псевдоним — приходится постоянно переключаться. Этот сервер хранит учётные данные для любого количества авторизованных вами аккаунтов Gmail и направляет каждый вызов к тому, который вы указали.

Related MCP server: multiGmailMCP

Требования

• Node.js 20 или новее

• Проект Google Cloud с включённым Gmail API и OAuth-клиент типа Desktop app

1. Получите OAuth-клиент Google

1. Откройте Google Cloud Console и выберите или создайте проект.

2. APIs & Services → Library → включите Gmail API.

3. APIs & Services → OAuth consent screen → настройте его. Пока приложение находится в Testing, добавьте каждый адрес Gmail, который планируете подключать, в раздел Test users.

4. APIs & Services → Credentials → Create credentials → OAuth client ID → тип приложения Desktop app. Скачайте JSON.

Клиенты типа Desktop app разрешают loopback-редиректы на любом порту — именно это использует процесс add-account.

2. Установка и сборка

git clone <this repo>
cd Gmail-MCP
npm install
npm run build

3. Укажите серверу ваш OAuth-клиент

Выберите один:

# Option A — save the downloaded JSON where the server looks by default
mkdir -p ~/.gmail-mcp && cp ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

# Option B — point at it explicitly
export GMAIL_MCP_CREDENTIALS=/path/to/client_secret.json

# Option C — pass the values directly
export GMAIL_MCP_CLIENT_ID=...apps.googleusercontent.com
export GMAIL_MCP_CLIENT_SECRET=...

4. Авторизуйте каждый почтовый ящик

Запустите один раз для каждого аккаунта Gmail:

node dist/index.js add-account --alias work
node dist/index.js add-account --alias personal
node dist/index.js list-accounts

Каждый запуск выводит URL согласия Google, ожидает редирект на локальном loopback-порту и сохраняет полученный refresh token. На машине без графического интерфейса добавьте --manual и вставьте URL, на который произошёл редирект.

Аккаунты, добавленные во время работы сервера, подхватываются автоматически — перезапуск не требуется.

5. Подключите его к Claude

Claude Code

claude mcp add gmail-multi -- node /absolute/path/to/Gmail-MCP/dist/index.js

Claude Desktop — добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": ["/absolute/path/to/Gmail-MCP/dist/index.js"],
      "env": {
        "GMAIL_MCP_CREDENTIALS": "/absolute/path/to/client_secret.json"
      }
    }
  }
}

Выбор аккаунта

Каждый инструмент, кроме list_accounts, принимает account. Он сопоставляется по порядку:

1. с полным адресом электронной почты — mikael@example.com

2. с псевдонимом, заданным при add-account, — work

3. с локальной частью до @ — mikael

4. с любым однозначным префиксом

account необязателен, когда настроен только один почтовый ящик или установлена переменная GMAIL_MCP_DEFAULT_ACCOUNT. В остальных случаях он обязателен, и в ошибке перечисляется, что доступно.

ID привязаны к почтовому ящику. ID сообщения, цепочки, черновика или метки из одного аккаунта ничего не значит в другом. Ошибка «not found» обычно означает, что был передан неверный account.

Инструменты

35 инструментов — набор инструментов коннектора плюс два для нескольких аккаунтов.

Названия инструментов намеренно совпадают с коннектором Gmail, поэтому подсказки и привычки переносятся без изменений. MCP-клиенты разделяют инструменты по серверам, поэтому оба набора можно включить одновременно без конфликтов.

Отличия от встроенного коннектора

Всё ниже — только дополнения: ничто из того, что делает коннектор, здесь не работает иначе.

• account в каждом инструменте, плюс list_accounts и get_profile.

• response_format (markdown | json) в каждом инструменте. По умолчанию используется Markdown, и он остаётся компактным; полная структурированная нагрузка в любом случае возвращается в structuredContent.

• delete_draft и get_message_attachment, которые коннектор упоминает, но не предоставляет.

• reply принимает quoteOriginal (по умолчанию false), чтобы добавить исходное сообщение цитируемым блоком.

• forward принимает includeAttachments (по умолчанию true); установите false, чтобы пропустить большие файлы.

• get_message_attachment принимает savePath, чтобы записать файл на диск вместо встраивания base64.

• Ответы ограничены 25 000 символов; в первую очередь сокращаются постраничные списки, и в ответе точно указывается, что было отброшено и как получить остальное.

Поведение, о котором стоит знать

• search_threads возвращает предпросмотр самых старых сообщений каждой цепочки (~5), как коннектор. Вызывайте get_thread, прежде чем отвечать на что-либо о недавних или непрочитанных письмах.

• Черновики исключаются из search_threads, если только в запросе не упоминаются черновики. Используйте list_drafts.

• Метки задаются по ID, а не по отображаемому имени. Сначала вызовите list_labels.

• DRAFT и SENT доступны только для чтения; добавление TRASH/SPAM перенаправляется в инструменты apply_sensitive_*, чтобы разрушающие действия всегда были явно названы.

• update_draft объединяет поля, но вложения заменяются, а не объединяются — в ответе сообщается, сколько было отброшено.

• reply устанавливает In-Reply-To и References, чтобы клиенты правильно строили цепочки, и никогда не адресует ответ самому авторизованному почтовому ящику.

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

• Refresh-токены хранятся в ~/.gmail-mcp/accounts.json и записываются атомарно с правами 0600 в каталоге с правами 0700. Любой, у кого есть доступ на чтение к этому файлу, имеет полный доступ к почтовым ящикам.

• OAuth-процесс проверяет параметр state и слушает только на 127.0.0.1.

• remove-account удаляет локальный токен. Чтобы полностью отозвать доступ, удалите также приложение на myaccount.google.com/permissions.

• Предоставленные области доступа позволяют читать, отправлять и удалять почту. send_message, reply и forward доставляют письмо немедленно — в описаниях инструментов указано, что модели следует предпочитать create_draft, когда пользователь явно не попросил отправить письмо.

Разработка

npm run build         # compile TypeScript to dist/
npm test              # build, then unit tests + stdio smoke test
npm run test:unit     # MIME, reply addressing, parsing, truncation — no network
npm run test:smoke    # boots the server, checks all 35 tools register
npm run inspect       # open the MCP Inspector against the server

src/
  index.ts            CLI entry point and server bootstrap
  constants.ts        scopes, limits, paths
  types.ts            normalized message/thread/draft shapes
  auth/               token store, OAuth flow, account registry
  schemas/common.ts   shared Zod fields (account, formats, pagination, colors)
  services/           Gmail parsing, MIME building, formatting, errors
  tools/              tool registration by domain

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

Лицензия

MIT