gmail-reader

MCP-сервер, через который AI-агент (Claude Code и т.п.) читает твой Gmail — но только письма с теми адресами и доменами, что ты разрешил проекту. Парный проект: tg-reader для Telegram.

• Каждый проект подключает свой профиль — список адресов (ivan@client.ru) и доменов (@client.ru). Письмо видно, только если профиль есть в From/To/Cc/Bcc. Спам, корзина и черновики не видны.

• OAuth-права ровно gmail.readonly + gmail.send: удалять, архивировать, ставить ярлыки и отмечать прочитанным токен не может в принципе.

• Отправка (reply, send_message) — только если в профиле write = true. Новое письмо уходит только на адреса профиля; reply разрешён лишь в ветке, где адрес профиля или ты сам уже писали.

• Письма от отправителей без DKIM/DMARC читаются с пометкой, но ответить на них нельзя.

• Вложения на отправку берутся только внутри --upload-root, скрытые пути отвергаются.

• Содержимое писем — недоверенные данные; сервер подсказывает агенту не исполнять инструкции из писем.

⚠️ Прежде чем ставить

• Refresh-токен — это чтение всей почты и отправка от твоего имени. Храни его как пароль: менеджер паролей или файл с правами 600, никогда не в git и не в чат с агентом.

• Отозвать доступ: https://myaccount.google.com/connections → удалить приложение.

Related MCP server: Postfleet MCP

Установка

git clone https://github.com/agentseo/gmail-reader ~/gmail-reader && cd ~/gmail-reader
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

1. Своё OAuth-приложение в Google Cloud

Каждый создаёт своё — это бесплатно, минут 10. https://console.cloud.google.com/:

1. Создать проект.

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

3. OAuth consent screen → тип External, свой адрес — в Test users.

4. Publish app → статус In production (верификация не нужна). Пока приложение в «Testing», Google обрывает токен через 7 дней. При входе будет «приложение не проверено» — это ожидаемо: Advanced → перейти.

5. Credentials → Create credentials → OAuth client ID → Desktop app. Скопировать client id и client secret.

2. Вход

export GMAIL_CLIENT_ID=... GMAIL_CLIENT_SECRET=...
mkdir -p ~/.config/gmail-reader
(umask 077; .venv/bin/python -m gmail_reader.login --raw > ~/.config/gmail-reader/token)

Ссылка согласия печатается в терминал; открой её, разреши доступ. Токен попадает только в файл. Под WSL браузер на Windows должен достучаться до localhost WSL; если страница после согласия не открылась — открой ссылку в браузере внутри WSL.

Проверка: GMAIL_REFRESH_TOKEN_FILE=~/.config/gmail-reader/token .venv/bin/python -m gmail_reader.whoami печатает адрес ящика.

3. Профиль

cp profiles.example.toml profiles.toml, вписать адреса и домены.

Подключение к проекту

.mcp.json в корне проекта (пути — свои):

{
  "mcpServers": {
    "gmail": {
      "command": "/home/me/gmail-reader/.venv/bin/python",
      "args": [
        "-m", "gmail_reader.server",
        "--profile", "myproject",
        "--download-dir", "/home/me/projects/myproject/mail-files"
      ],
      "env": {
        "PYTHONPATH": "/home/me/gmail-reader",
        "GMAIL_CLIENT_ID": "${GMAIL_CLIENT_ID}",
        "GMAIL_CLIENT_SECRET": "${GMAIL_CLIENT_SECRET}",
        "GMAIL_REFRESH_TOKEN_FILE": "/home/me/.config/gmail-reader/token"
      }
    }
  }
}

• ${...} Claude Code подставит из окружения шелла — секреты не лежат в .mcp.json.

• --upload-root <dir> включает вложения на отправку (и только если write = true).

• mail-files/ добавь в .gitignore проекта.

• Правка profiles.toml подхватывается после перезапуска сервера (новая сессия агента).

Переменные

Токен отзывается при смене пароля Google и после 6 месяцев без использования — тогда войти заново.

Тесты

.venv/bin/python -m pytest

Как есть, без гарантий. Лицензия MIT.