notifications-mcp

Unified Notifications MCP Server — Phase 1: Gmail Senden Sie E-Mail-Benachrichtigungen von jedem KI-Agenten (Claude, LangGraph, GPT) über das Model Context Protocol.

Was dies tut

Dieser MCP-Server stellt ein mail_send-Tool bereit, das jeder MCP-kompatible KI-Agent aufrufen kann, um E-Mails über Gmail zu senden.

Anwendungsfall: Eine Fabrikmaschine fällt aus → Ihr KI-Überwachungsagent ruft mail_send auf → Manager, Techniker und Mitarbeiter erhalten sofort eine Alarm-E-Mail.

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

MCP-Endpunkt: http://localhost:8100/mcp

Architektur

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)

Um einen neuen Kanal hinzuzufügen: Erstellen Sie channels/<name>/tools.py mit einer register(mcp, cfg)-Funktion, fügen Sie den Kanalnamen zu enabled_channels in config.yaml hinzu. Keine anderen Dateien ändern sich.

Einrichtung

1. Voraussetzungen

• Python 3.11+

• Ein Google Cloud-Projekt mit aktivierter Gmail-API

2. Google Cloud Einrichtung

1. Gehen Sie zur Google Cloud Console

2. Aktivieren Sie die Gmail-API für Ihr Projekt

3. Gehen Sie zu APIs & Services → Anmeldedaten → Anmeldedaten erstellen → OAuth 2.0-Client-ID

4. Anwendungstyp: Webanwendung

5. Fügen Sie autorisierte Weiterleitungs-URI hinzu: http://localhost:8100/auth/gmail/callback

6. Laden Sie das JSON herunter → speichern Sie es als credentials/google_credentials.json

3. Abhängigkeiten installieren

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

4. Server starten

python -m src.server

Sie sehen:

{"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 authentifizieren (nur beim ersten Mal)

Öffnen Sie Ihren Browser und besuchen Sie:

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

1. Sie werden zur Google-Zustimmungsseite weitergeleitet

2. Melden Sie sich mit dem Gmail-Konto an, von dem Sie senden möchten

3. Erteilen Sie die Berechtigung „E-Mail senden“

4. Sie sehen ✅ Gmail Authentifiziert! — schließen Sie den Tab

5. Das Token wird in credentials/gmail_token.json gespeichert und von nun an automatisch im Hintergrund erneuert

Verwenden des mail_send-Tools

Vom MCP Inspector (Testen)

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

Rufen Sie mail_send auf mit:

{
  "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."
}

Von einem KI-Agenten (Claude / LangGraph)

Der Agent sieht diese Tool-Beschreibung:

mail_send — Senden Sie eine E-Mail über Gmail an einen oder mehrere Empfänger. Fügen Sie bei Maschinenausfall-Benachrichtigungen den Maschinennamen, den Standort, die Stoppzeit und den Fehlercode hinzu.

Der Agent ruft es auf als:

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."
})

Von Antigravity / Claude Desktop

Fügen Sie zu Ihrer MCP-Konfiguration hinzu:

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

Tool-Referenz

mail_send

Senden Sie eine E-Mail an einen oder mehrere Empfänger über Gmail.

Rückgabe bei Erfolg:

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

Rückgabe bei Fehler:

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

Konfiguration

Bearbeiten Sie config.yaml, um Einstellungen zu ändern:

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"

Tests ausführen

pytest tests/ -v

Erwartete Ausgabe:

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

Hinzufügen von Phase 2 (Teams) oder Phase 3 (SMS)

1. Erstellen Sie den Kanalordner:

   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. Fügen Sie zu config.yaml hinzu:

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

3. Fertig. server.py und registry.py benötigen null Änderungen.

Sicherheitshinweise

• credentials/ ist in gitignore — niemals Google-Anmeldedaten committen

• OAuth-Token wird automatisch im Hintergrund erneuert — Sie stimmen nur einmal zu

• Der Server läuft auf localhost — standardmäßig nicht im Internet erreichbar

• Für localhost ist kein API-Schlüssel erforderlich

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