Gmail MCP Server

Этот проект реализует сервер Model Context Protocol (MCP), который позволяет взаимодействовать с аккаунтами Gmail через IMAP и SMTP. Он предоставляет инструменты для поиска писем, получения содержимого, управления метками (создание, удаление, переименование, применение, снятие) и отправки/пересылки писем.

Возможности

• Поиск писем: Поиск писем по диапазону дат, ключевому слову или необработанной строке запроса Gmail. Поддерживает поиск в конкретных папках (входящие, отправленные) и ограничение результатов. Использует расширение Gmail X-GM-RAW для эффективного поиска во входящих (например, фильтрация по category:primary).

• Получение содержимого письма: Получение полного содержимого (заголовки, тело, вложения) конкретного письма по его идентификатору последовательности.

• Управление метками (CRUD):

  • Список всех доступных меток Gmail (папок).

  • Создание новых пользовательских меток.

  • Переименование существующих пользовательских меток.

  • Удаление существующих пользовательских меток (системные метки удалять нельзя).

  • Применение меток к отдельным письмам.

  • Снятие меток с отдельных писем.

• Пакетные операции:

  • Применение меток к нескольким письмам одновременно с использованием идентификаторов последовательности.

  • Снятие меток с нескольких писем одновременно.

  • Перемещение нескольких писем в конкретную метку/папку.

• Отправка писем: Отправка новых писем (требуется настройка SMTP).

• Пересылка писем: Пересылка существующих писем, включая вложения (требуется настройка SMTP).

• Ежедневное количество писем: Подсчет писем, полученных за день, в пределах указанного диапазона дат.

Related MCP server: Gmail MCP Server

Структура проекта

.
├── .gitignore         # Specifies intentionally untracked files that Git should ignore
├── .python-version    # Specifies Python version (used by pyenv)
├── LICENSE            # Project license file
├── pyproject.toml     # Python project configuration (dependencies, build system)
├── README.md          # This file
├── task_list.md       # Tracks development progress
├── uv.lock            # Lock file for uv package manager
├── src/
│   └── email_client/
│       ├── __init__.py
│       ├── config.py        # Handles loading configuration from environment variables (.env)
│       ├── handlers.py      # Implements the logic for handling MCP tool calls
│       ├── imap_client.py   # Contains functions for interacting with IMAP server
│       ├── server.py        # Main MCP server script using @modelcontextprotocol/sdk
│       ├── smtp_client.py   # Contains functions for interacting with SMTP server
│       ├── tool_definitions.py # Defines the available MCP tools and their schemas
│       └── utils.py         # Utility functions (e.g., email parsing, date formatting)
└── ... (other potential files like test scripts, helper scripts)

Настройка

1. Клонируйте репозиторий (если применимо):

   git clone https://github.com/david-strejc/gmail-mcp-server.git
   cd gmail-mcp-server

2. Установка зависимостей: Этот проект использует uv для управления пакетами.

   # Ensure uv is installed (e.g., pip install uv)
   uv venv  # Create virtual environment (.venv)
   uv sync  # Install dependencies from pyproject.toml and uv.lock
   source .venv/bin/activate # Activate the virtual environment

   (В качестве альтернативы, если вы не используете uv, создайте виртуальное окружение и установите зависимости с помощью pip install -r requirements.txt, если файл requirements.txt создан).

3. Настройка переменных окружения: Создайте файл .env в корневом каталоге проекта и добавьте свои учетные данные Gmail и настройки сервера:

   # .env file
   GMAIL_EMAIL=your_email@gmail.com
   GMAIL_PASSWORD=your_app_password # Use an App Password if 2FA is enabled
   GMAIL_IMAP_SERVER=imap.gmail.com
   GMAIL_SMTP_SERVER=smtp.gmail.com
   GMAIL_SMTP_PORT=587 # Or 465 for SSL

   • Важно: Для Gmail, если у вас включена двухфакторная аутентификация, вы обязаны создать и использовать «пароль приложения». Обычные пароли не будут работать. См. документацию Google о паролях приложений.

   • Убедитесь, что «Доступ к ненадежным приложениям» включен, если вы не используете 2FA (обычно это не рекомендуется).

Запуск MCP-сервера

Активируйте виртуальное окружение и запустите скрипт сервера:

source .venv/bin/activate
python src/email_client/server.py

Сервер запустится и будет ожидать MCP-запросы через стандартный ввод/вывод.

Интеграция с MCP-клиентом (например, Cline)

Добавьте конфигурацию сервера в файл настроек вашего MCP-клиента (например, cline_mcp_settings.json или claude_desktop_config.json).

Пример записи в cline_mcp_settings.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/your/project/gmail-mcp-server/.venv/bin/python",
      "args": ["/path/to/your/project/gmail-mcp-server/src/email_client/server.py"],
      "env": {}, // Environment variables are loaded from .env by the script
      "enabled": true, // Set to true to enable
      "autoApprove": [] // Configure auto-approval if desired
    }
    // ... other servers
  }
}

• Замените /path/to/your/project/gmail-mcp-server на фактический абсолютный путь к этому каталогу проекта.

• Убедитесь, что command указывает на исполняемый файл python в виртуальном окружении проекта (.venv/bin/python).

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

Доступные инструменты (сводка)

• search-emails: Поиск писем.

• get-email-content: Получение полных сведений о письме.

• count-daily-emails: Подсчет писем за день.

• list-labels: Список всех меток/папок.

• create-label: Создание новой метки.

• rename-label: Переименование существующей метки.

• delete-label: Удаление метки.

• apply-label: Применение метки к одному письму.

• remove-label: Снятие метки с одного письма.

• apply-label-batch: Применение метки к нескольким письмам.

• remove-label-batch: Снятие метки с нескольких писем.

• move-email: Перемещение одного письма в метку.

• move-email-batch: Перемещение нескольких писем в метку.

• send-email: Отправка нового письма.

• forward-email: Пересылка существующего письма.

Обратитесь к src/email_client/tool_definitions.py за подробными схемами входных данных для каждого инструмента.