Graph Mail MCP

Un servidor local Model Context Protocol de stdio para el correo de Microsoft 365. Proporciona flujos controlados de búsqueda, lectura, hilos, adjuntos y borradores de Outlook/Exchange Online a través de Microsoft Graph.

Nunca envía, elimina, mueve, copia, archiva ni marca mensajes como leídos. No se exponen URL sin procesar de Graph, OData sin procesar ni solicitudes Graph sin restricciones.

Requisitos

• Windows con Microsoft Edge

• Node.js 22+

• Una cuenta de Microsoft 365 de trabajo o centro educativo con Exchange Online

• Permiso delegado Mail.ReadWrite

Las cuentas personales de Microsoft están deshabilitadas por defecto. Los buzones compartidos requieren además delegación de Exchange y Mail.ReadWrite.Shared.

Instalación

git clone https://github.com/hanhandly/graph-mail-mcp.git
Set-Location graph-mail-mcp
npm ci
npm run build
Copy-Item config.example.json config.local.json

Git ignora config.local.json. Revísalo antes de la autenticación, especialmente tenant, allowedMailboxScopes y la configuración de buzones compartidos.

Autenticación

node dist\cli.js -c config.local.json doctor
node dist\cli.js -c config.local.json auth login --account-hint user@contoso.com
node dist\cli.js -c config.local.json auth status

El inicio de sesión abre un perfil aislado de Microsoft Edge y usa Graph Explorer para la autenticación delegada. Playwright hace clic en Iniciar sesión, selecciona la cuenta sugerida y comprueba si el permiso de correo requerido ya está consentido. Si lo está, la autenticación continúa automáticamente; de lo contrario, la CLI indica al usuario qué permiso debe concederse. Playwright nunca hace clic en Consentir. El MFA y la confirmación de consentimiento siguen bajo control del usuario. auth status devuelve solo metadatos y nunca muestra el token.

Configurar un cliente MCP

Usa rutas absolutas en la configuración MCP del cliente:

{
  "mcpServers": {
    "graph-mail": {
      "command": "node",
      "args": [
        "C:\\Tools\\graph-mail-mcp\\dist\\cli.js",
        "-c",
        "C:\\Tools\\graph-mail-mcp\\config.local.json",
        "serve"
      ],
      "cwd": "C:\\Tools\\graph-mail-mcp"
    }
  }
}

Algunos clientes usan una clave externa distinta, pero los valores de command, args y cwd son los mismos. Mantén -c <config-path> antes de serve. El servidor usa stdio y no abre un puerto de red.

Reinicia el cliente MCP y luego llama a:

1. mail_auth_status

2. mail_list_folders

3. mail_search_messages

Herramientas

Las actualizaciones de borradores se limitan a los borradores creados y registrados por este MCP. No hay herramienta de envío.

Seguridad

El transporte de Graph usa un firewall de políticas de denegación por defecto y un compilador de solicitudes tipadas. Los tokens se almacenan fuera del repositorio y están protegidos con DPAPI de Windows por defecto. Los registros y las respuestas de las herramientas no deben exponer tokens de acceso, cookies ni encabezados de autorización.

Graph Explorer puede devolver permisos previamente consentidos a su aplicación compartida. El servidor rechaza Mail.Send y restringe las solicitudes en tiempo de ejecución, pero las implementaciones que requieran un token de privilegios mínimos estrictos deben usar un registro de aplicación dedicado o un proveedor de autenticación restringido.

Consulta Seguridad, Referencia de herramientas, Ejemplo de configuración y Arquitectura.# Graph Mail MCP

Un servidor local Model Context Protocol de stdio para el correo de Microsoft 365. Proporciona flujos de trabajo controlados de búsqueda, lectura, hilos, adjuntos y borradores de Outlook/Exchange Online a través de Microsoft Graph.

Nunca envía, elimina, mueve, copia, archiva ni marca mensajes como leídos. No se exponen URL sin procesar de Graph, OData sin procesar ni solicitudes Graph sin restricciones.

Requisitos

• Windows con Microsoft Edge

• Node.js 22+

• Una cuenta de Microsoft 365 de trabajo o centro educativo con Exchange Online

• Permiso delegado Mail.ReadWrite

Las cuentas personales de Microsoft están deshabilitadas por defecto. Los buzones compartidos requieren además delegación de Exchange y Mail.ReadWrite.Shared.

Instalación

git clone https://github.com/hanhandly/graph-mail-mcp.git
Set-Location graph-mail-mcp
npm ci
npm run build
Copy-Item config.example.json config.local.json

Git ignora config.local.json. Revísalo antes de la autenticación, especialmente tenant, allowedMailboxScopes y la configuración de buzones compartidos.

Autenticación

node dist\cli.js -c config.local.json doctor
node dist\cli.js -c config.local.json auth login --account-hint user@contoso.com
node dist\cli.js -c config.local.json auth status

El inicio de sesión abre un perfil aislado de Microsoft Edge y usa Graph Explorer para la autenticación delegada. Playwright hace clic en Iniciar sesión, selecciona la cuenta sugerida y comprueba si el permiso de correo requerido ya está consentido. Si lo está, la autenticación continúa automáticamente; de lo contrario, el CLI indica al usuario qué permiso debe concederse. Playwright nunca hace clic en Consentir. El MFA y la confirmación de consentimiento siguen bajo control del usuario. auth status devuelve solo metadatos y nunca muestra el token.

Configurar un cliente MCP

Usa rutas absolutas en la configuración de MCP del cliente:

{
  "mcpServers": {
    "graph-mail": {
      "command": "node",
      "args": [
        "C:\\Tools\\graph-mail-mcp\\dist\\cli.js",
        "-c",
        "C:\\Tools\\graph-mail-mcp\\config.local.json",
        "serve"
      ],
      "cwd": "C:\\Tools\\graph-mail-mcp"
    }
  }
}

Algunos clientes usan una clave externa distinta, pero los valores de command, args y cwd son los mismos. Mantén -c <config-path> antes de serve. El servidor usa stdio y no abre un puerto de red.

Reinicia el cliente de MCP y luego llama a:

1. mail_auth_status

2. mail_list_folders

3. mail_search_messages

Herramientas

Las actualizaciones de borradores se limitan a los borradores creados y registrados por este MCP. No hay herramienta de envío.

Seguridad

El transporte de Graph usa un firewall de política de denegación por defecto y un compilador de solicitudes tipadas. Los tokens se almacenan fuera del repositorio y están protegidos con DPAPI de Windows por defecto. Los registros y las respuestas de las herramientas no deben exponer tokens de acceso, cookies ni encabezados de autorización.

Graph Explorer puede devolver permisos previamente consentidos a su aplicación compartida. El servidor rechaza Mail.Send y restringe las solicitudes en tiempo de ejecución, pero las implementaciones que requieran un token de privilegios mínimos estrictos deben usar un registro de aplicación dedicado o un proveedor de autenticación restringido.

Consulta Seguridad, Referencia de herramientas, Ejemplo de configuración y Arquitectura.