# gmail-reader

MCP-сервер, через который AI-агент (Claude Code и т.п.) читает твой Gmail — но **только письма
с теми адресами и доменами, что ты разрешил проекту**. Парный проект:
[tg-reader](https://github.com/agentseo/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> → удалить приложение.

## Установка

```bash
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](https://console.cloud.google.com/apis/library/gmail.googleapis.com) →
   включить **Gmail API**.
3. [OAuth consent screen](https://console.cloud.google.com/auth/overview) → тип **External**,
   свой адрес — в Test users.
4. **Publish app** → статус **In production** (верификация не нужна). Пока приложение в
   «Testing», Google обрывает токен через 7 дней. При входе будет «приложение не проверено» —
   это ожидаемо: Advanced → перейти.
5. [Credentials](https://console.cloud.google.com/apis/credentials) → Create credentials →
   OAuth client ID → **Desktop app**. Скопировать client id и client secret.

### 2. Вход

```bash
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` в корне проекта (пути — свои):

```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` подхватывается после перезапуска сервера (новая сессия агента).

## Переменные

| Env                        | Что                                          |
| -------------------------- | -------------------------------------------- |
| `GMAIL_CLIENT_ID`          | OAuth client id (Desktop app)                |
| `GMAIL_CLIENT_SECRET`      | OAuth client secret                          |
| `GMAIL_REFRESH_TOKEN`      | refresh-токен (или вместо него ↓)            |
| `GMAIL_REFRESH_TOKEN_FILE` | путь к файлу с refresh-токеном               |

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

## Тесты

`.venv/bin/python -m pytest`

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