gmail-mcp v1.0.0

Унифицированный MCP-сервер Google OAuth2 для Gmail с поддержкой нескольких аккаунтов. Ищите, читайте, создавайте, отправляйте, сохраняйте в черновики и организуйте письма в нескольких аккаунтах Google без каких-либо усилий.

Возможности (4 унифицированных инструмента)

• gmail_search: Поиск писем с использованием официального синтаксиса поиска Gmail (is:unread, from:boss@corp.com, subject:invoice, newer_than:2d, has:attachment)

• gmail_read: Чтение полного содержимого письма и метаданных (тема, отправитель, текст письма, HTML, CC, BCC, метки, список вложений)

• gmail_send: Отправка писем или создание черновиков (поддержка HTML, CC, BCC, ответов в ветках и вложений)

• gmail_manage: Управление метками, архивирование, работа с корзиной, переключение прочитано/непрочитано, безвозвратное удаление и инвентаризация нескольких аккаунтов

Related MCP server: Moist

Архитектура с несколькими аккаунтами

Один OAuth-клиент Google Cloud (credentials.json) может аутентифицировать несколько аккаунтов Gmail. Токены хранятся для каждого аккаунта в ~/.secrets/gmail/tokens/<account_name>.json.

1. Настройка учетных данных Google OAuth (однократно)

1. Создайте проект в Google Cloud Console.

2. Включите Gmail API.

3. Создайте OAuth 2.0 Client ID (десктопное приложение).

4. Скачайте JSON-файл с секретом клиента и сохраните его как ~/.secrets/gmail/credentials.json (или задайте переменную GMAIL_CREDENTIALS_JSON).

2. Аутентификация аккаунтов

Запустите интерактивный CLI авторизации для каждого аккаунта:

gmail-auth default    # Authenticates primary account
gmail-auth work       # Authenticates secondary work account
gmail-auth client_x   # Authenticates any additional account

Выведите список всех аутентифицированных аккаунтов:

gmail-auth --list

Установка в MCP-клиентах (Claude Desktop, OpenCode, Cursor, Windsurf)

Вариант 1: Мгновенно через uvx (рекомендуется)

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Steph-ux/gmail-mcp.git", "gmail-mcp"]
    }
  }
}

Вариант 2: Через pip install

pip install git+https://github.com/Steph-ux/gmail-mcp.git

Затем в вашем MCP-конфиге:

{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp"
    }
  }
}

Вариант 3: Локальный клон (для разработки)

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["D:\\Steph\\script\\gmail-mcp\\server.py"]
    }
  }
}

Примеры использования

1. Поиск сообщений

# Search in default account:
gmail_search(query='is:unread from:github')

# Search in work account:
gmail_search(account='work', query='subject:invoice newer_than:7d')

2. Чтение сообщения

gmail_read(account='work', message_id='18f2a9b4c10d')

3. Отправка письма или создание черновика

# Send direct email:
gmail_send(
    account='default',
    to='colleague@example.com',
    subject='Project Update',
    body_text='Here is the latest status...',
    body_html='<h1>Project Update</h1><p>Here is the latest status...</p>'
)

# Create a draft:
gmail_send(
    account='work',
    to='client@example.com',
    subject='Proposal draft',
    body_text='Please review the proposal.',
    draft=True
)

4. Организация и управление

# Archive email:
gmail_manage(account='work', action='archive', message_id='18f2a9b4c10d')

# Mark as unread:
gmail_manage(account='default', action='mark_unread', message_id='18f2a9b4c10d')

# Move to trash:
gmail_manage(account='default', action='trash', message_id='18f2a9b4c10d')

# List active accounts:
gmail_manage(action='list_accounts')

Тестирование

pytest tests

Лицензия

MIT