notifications-mcp

Unified Notifications MCP Server — Phase 1: Gmail
Отправляйте оповещения по электронной почте из любого AI-агента (Claude, LangGraph, GPT) через Model Context Protocol.

Что это делает

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

Сценарий использования: Заводской станок останавливается → ваш AI-агент мониторинга вызывает mail_send → менеджер, техник и персонал мгновенно получают оповещение по электронной почте.

Machine stops → AI Agent → mail_send tool → Gmail → Manager + Technician notified

MCP-эндпоинт: http://localhost:8100/mcp

Архитектура

notifications-mcp/
├── src/
│   ├── server.py          ← Entrypoint (Streamable HTTP + OAuth routes)
│   ├── config.py          ← Loads config.yaml
│   ├── registry.py        ← Dynamically loads channel tools
│   └── channels/
│       ├── mail/          ← Gmail channel (Phase 1)
│       ├── teams/         ← Microsoft Teams (Phase 2 placeholder)
│       └── sms/           ← SMS via Twilio (Phase 3 placeholder)

Чтобы добавить новый канал: создайте channels/<name>/tools.py с функцией register(mcp, cfg), добавьте имя канала в enabled_channels в config.yaml. Никакие другие файлы не изменяются.

Настройка

1. Предварительные требования

• Python 3.11+

• Проект Google Cloud с включённым Gmail API

2. Настройка Google Cloud

1. Перейдите в Google Cloud Console

2. Включите Gmail API для вашего проекта

3. Перейдите в APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID

4. Тип приложения: Web application

5. Добавьте авторизованный URI перенаправления: http://localhost:8100/auth/gmail/callback

6. Скачайте JSON → сохраните как credentials/google_credentials.json

3. Установка зависимостей

pip install -r requirements.txt
# or for development:
pip install -e ".[dev]"

4. Запуск сервера

python -m src.server

Вы увидите:

{"level": "INFO", "message": "Starting notifications-mcp | host=0.0.0.0 | port=8100"}
{"level": "INFO", "message": "MCP endpoint  → http://localhost:8100/mcp"}
{"level": "INFO", "message": "Gmail OAuth   → http://localhost:8100/auth/gmail/start"}

5. Аутентификация Gmail (только при первом запуске)

Откройте браузер и перейдите по адресу:

http://localhost:8100/auth/gmail/start

1. Вы будете перенаправлены на страницу согласия Google

2. Войдите в аккаунт Gmail, с которого будете отправлять письма

3. Разрешите разрешение "Отправлять электронные письма"

4. Вы увидите ✅ Gmail Authenticated! — закройте вкладку

5. Токен сохраняется в credentials/gmail_token.json и с этого момента автоматически обновляется без вашего участия

Использование инструмента mail_send

Из MCP Inspector (тестирование)

npx @modelcontextprotocol/inspector http://localhost:8100/mcp

Вызовите mail_send с:

{
  "to": ["manager@yourcompany.com", "technician@yourcompany.com"],
  "subject": "ALERT: Machine #3 stopped",
  "body": "Machine #3 on Floor B stopped at 18:02.\nError code: E-404.\nPlease investigate immediately."
}

Из AI-агента (Claude / LangGraph)

Агент видит такое описание инструмента:

mail_send — Отправить электронное письмо через Gmail одному или нескольким получателям. Для оповещений о простое заводского оборудования укажите название станка, местоположение, время остановки и код ошибки.

Агент вызывает его так:

result = await client.call_tool("mail_send", {
    "to": ["manager@factory.com", "tech@factory.com"],
    "subject": "ALERT: Machine #3 stopped",
    "body": "Machine #3 stopped at 18:02. Error: E-404. Location: Floor B, Line 2."
})

Из Antigravity / Claude Desktop

Добавьте в конфигурацию MCP:

{
  "mcpServers": {
    "notifications": {
      "url": "http://localhost:8100/mcp"
    }
  }
}

Справочник инструментов

mail_send

Отправить электронное письмо одному или нескольким получателям через Gmail.

Возвращает при успехе:

{"status": "sent", "message_id": "18b3c...", "recipients": ["manager@co.com"]}

Возвращает при ошибке:

{"status": "failed", "error": "rate_limited", "message": "Gmail rate limit hit. Wait 60s."}

Конфигурация

Отредактируйте config.yaml, чтобы изменить настройки:

server:
  host: "0.0.0.0"
  port: 8100          # Change port here

enabled_channels:
  - mail              # Add 'teams' or 'sms' here in Phase 2/3

channels:
  mail:
    credentials_path: "credentials/google_credentials.json"
    token_path: "credentials/gmail_token.json"
    scopes:
      - "https://www.googleapis.com/auth/gmail.send"
    oauth_redirect_uri: "http://localhost:8100/auth/gmail/callback"

Запуск тестов

pytest tests/ -v

Ожидаемый вывод:

tests/channels/mail/test_tools.py::test_mail_send_success PASSED
tests/channels/mail/test_tools.py::test_mail_send_not_authenticated PASSED
tests/channels/mail/test_tools.py::test_mail_send_rate_limited PASSED
tests/channels/mail/test_tools.py::test_mail_send_missing_to_field PASSED
tests/channels/mail/test_tools.py::test_mail_send_missing_subject PASSED
tests/channels/mail/test_tools.py::test_mail_send_multiple_recipients PASSED
tests/channels/mail/test_tools.py::test_mail_send_with_cc_bcc PASSED

Добавление Phase 2 (Teams) или Phase 3 (SMS)

1. Создайте папку канала:

   src/channels/teams/__init__.py
   src/channels/teams/auth.py
   src/channels/teams/client.py
   src/channels/teams/schemas.py
   src/channels/teams/tools.py   ← must have def register(mcp, cfg)

2. Добавьте в config.yaml:

   enabled_channels:
     - mail
     - teams       ← add this
   channels:
     teams:
       tenant_id: "..."
       client_id: "..."

3. Готово. server.py и registry.py не требуют изменений.

Замечания по безопасности

• Каталог credentials/ добавлен в .gitignore — никогда не коммитьте учётные данные Google

• OAuth-токен автоматически обновляется без вашего участия — согласие даётся только один раз

• Сервер работает на localhost — по умолчанию не доступен из интернета

• Для работы на localhost не требуется API-ключ

Phase 1: Gmail ✅ | Phase 2: Teams 🔜 | Phase 3: SMS 🔜