notifications-mcp

Servidor MCP de Notificaciones Unificado — Fase 1: Gmail
Enviar alertas por correo electrónico desde cualquier agente de IA (Claude, LangGraph, GPT) mediante el Protocolo de Contexto de Modelo.

Qué Hace Esto

Este servidor MCP expone una herramienta mail_send que cualquier agente de IA compatible con MCP puede llamar para enviar correos electrónicos a través de Gmail.

Caso de uso: Una máquina de fábrica deja de funcionar → tu agente de monitoreo de IA llama a mail_send → el gerente, el técnico y el personal reciben un correo de alerta al instante.

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

Endpoint MCP: http://localhost:8100/mcp

Arquitectura

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)

Para agregar un nuevo canal: crea channels/<nombre>/tools.py con una función register(mcp, cfg), agrega el nombre del canal a enabled_channels en config.yaml. No es necesario modificar ningún otro archivo.

Configuración

1. Requisitos previos

• Python 3.11+

• Un proyecto de Google Cloud con la API de Gmail habilitada

2. Configuración de Google Cloud

1. Ve a Consola de Google Cloud

2. Habilita la API de Gmail para tu proyecto

3. Ve a APIs y Servicios → Credenciales → Crear credenciales → ID de cliente OAuth 2.0

4. Tipo de aplicación: Aplicación web

5. Agrega URI de redireccionamiento autorizado: http://localhost:8100/auth/gmail/callback

6. Descarga el JSON → guárdalo como credentials/google_credentials.json

3. Instalar Dependencias

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

4. Iniciar el Servidor

python -m src.server

Verás:

{"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. Autenticar Gmail (Solo la Primera Vez)

Abre tu navegador y visita:

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

1. Serás redirigido a la página de consentimiento de Google

2. Inicia sesión con la cuenta de Gmail desde la que deseas ENVIAR

3. Concede el permiso "Enviar correo electrónico"

4. Verás ✅ ¡Gmail Autenticado! — cierra la pestaña

5. El token se guarda en credentials/gmail_token.json y se renueva automáticamente de forma silenciosa a partir de ahora

Usar la Herramienta mail_send

Desde MCP Inspector (pruebas)

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

Llama a mail_send con:

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

Desde un Agente de IA (Claude / LangGraph)

El agente ve esta descripción de la herramienta:

mail_send — Enviar un correo electrónico a través de Gmail a uno o más destinatarios. Para alertas de parada de máquina en fábrica, incluye el nombre de la máquina, ubicación, hora de parada y código de error.

El agente la llama así:

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

Desde Antigravity / Claude Desktop

Agrega a tu configuración de MCP:

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

Referencia de Herramientas

mail_send

Envía un correo electrónico a uno o más destinatarios a través de Gmail.

Devuelve en caso de éxito:

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

Devuelve en caso de error:

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

Configuración

Edita config.yaml para cambiar la configuración:

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"

Ejecutar Pruebas

pytest tests/ -v

Salida esperada:

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

Agregar Fase 2 (Teams) o Fase 3 (SMS)

1. Crea la carpeta del canal:

   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. Agrega a config.yaml:

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

3. Listo. server.py y registry.py no necesitan cambios.

Notas de Seguridad

• credentials/ está en .gitignore — nunca subas credenciales de Google

• El token OAuth se renueva automáticamente de forma silenciosa — solo das consentimiento una vez

• El servidor se ejecuta en localhost — no está expuesto a internet por defecto

• No se requiere clave API para uso en localhost

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