mcp-outlook

Un servidor MCP autoalojable para Microsoft Exchange local a través de EWS (Exchange Web Services). Diseñado para entornos aislados / sin nube: se comunica directamente con tu servidor Exchange interno y nunca toca Microsoft Graph, Azure AD ni un cliente de escritorio de Outlook.

• Backend: exchangelib (cliente EWS)

• Framework: FastMCP

• Transporte: streamable-http (un servidor HTTP independiente al que se conectan otros hosts internos)

• Autenticación con Exchange: básica o NTLM (seleccionable mediante configuración)

Dos modos

Cómo el modo jwt tiende un puente entre identidades. Exchange no puede consumir los JWT de tu empresa (Outlook se basa en PKINIT/Kerberos). Por eso el MCP realiza dos autenticaciones separadas que nunca se mezclan:

User --(JWT)--> MCP validates the token, reads the user's email
                MCP --(service account, NTLM)--> Exchange
                MCP --(impersonation header = user's email)--> acts on the user's mailbox

El JWT del usuario nunca se envía a Exchange, y ninguna contraseña/tarjeta inteligente de usuario toca jamás el MCP: solo lo hace la única credencial de servicio. Consulta TODO.md para saber qué deben configurar los administradores para el modo jwt.

Related MCP server: OWA Exchange MCP Server

Herramientas

list_emails y search_emails también aceptan unread_only=true para devolver solo mensajes no leídos.

Instalación

Requiere Python 3.11+ y uv.

uv sync                 # create venv + install deps
cp .env.example .env    # then edit .env with your Exchange details
uv run python -m mcp_outlook

El servidor se vincula a MCP_HOST:MCP_PORT (por defecto 127.0.0.1:8000) y sirve el endpoint MCP streamable-http en /mcp.

Pruebas beta locales (sin configuración de administrador)

Ejecuta contra tu propio buzón con tu propio nombre de usuario/contraseña: sin JWT, sin suplantación, sin cuenta de servicio, sin tarjeta inteligente:

# in .env:
OUTLOOK_AUTH_MODE=static          # the default
OUTLOOK_EWS_ENDPOINT=https://mail.corp.local/EWS/Exchange.asmx
OUTLOOK_USERNAME=CORP\you
OUTLOOK_PASSWORD=...
uv run python -m mcp_outlook

Configuración

Todos los ajustes provienen de variables de entorno (o de un archivo .env). Consulta .env.example para ver la lista completa. Lo esencial:

Cómo encontrar tu endpoint de EWS

La URL de EWS no es la URL de OWA (webmail). En el servidor Exchange:

Get-WebServicesVirtualDirectory | fl Name,InternalUrl,ExternalUrl

En una instalación aislada casi siempre querrás la InternalUrl.

Pruebas

Las pruebas unitarias no necesitan servidor Exchange (solo análisis de configuración + serialización):

uv run pytest

Prueba de humo en vivo (con un .env real): inicia el servidor, conecta un cliente MCP o el MCP Inspector, y luego llama a list_folders → list_emails → send_email (a ti mismo) y confirma la recepción. Cambia OUTLOOK_AUTH_TYPE entre ntlm y basic para confirmar cuál tiene habilitado tu administrador de Exchange.

Interfaz de redacción (MCP Apps)

draft_email abre un widget interactivo de MCP Apps: un editor de React integrado en un único archivo HTML autocontenido (src/mcp_outlook/widgets/compose.html). Cualquier host compatible con MCP Apps lo renderiza en línea dentro del hilo de chat.

Funcionalidades del widget:

• Campo Para con búsqueda de contactos integrada: escribe después de la última coma para buscar contactos; selecciona un resultado para sustituir la consulta por un chip; las direcciones válidas se muestran como chips etiquetados.

• Enviar / Descartar: Enviar dispara send_email directamente desde el widget (solo para la app: el modelo no puede llamarlo); Descartar colapsa la tarjeta.

• Sustitución: abrir un nuevo borrador atenúa (pone en gris) cualquier widget de borrador anterior abierto.

• Firma: cada borrador se precarga con "Written with Airchat" (editable).

Garantía de aislamiento: el HTML generado (React + JS de puente incrustado) se distribuye con el paquete de Python. No se realizan solicitudes de recursos externos en tiempo de ejecución; Node.js solo se necesita para reconstruir el widget.

Reconstruir el widget (solo desarrollo)

cd frontend
npm ci
npm run build     # tsc + vite build + artifact copy → src/mcp_outlook/widgets/compose.html

El script de compilación verifica que no haya URLs externas en el HTML antes de copiarlo.

Pruébalo visualmente (vista previa de desarrollo independiente)

cd frontend && npm run dev
# Opens http://localhost:5173 with a mock host — no Exchange needed.
# Type in To, see chips form, contact results appear, Send/Discard collapse the card.

Advertencias

• La autenticación básica suele estar deshabilitada en Exchange moderno: NTLM es la opción predeterminada más segura.

• Los certificados internos/autofirmados requieren OUTLOOK_CA_BUNDLE; de lo contrario, la conexión falla en la verificación TLS.

• El modo multiusuario (jwt) necesita un permiso de Exchange: la cuenta de servicio debe tener el rol RBAC ApplicationImpersonation. Consulta TODO.md. El modo static no necesita ese permiso.

• .env contiene una contraseña en texto plano. Está ignorado por git; además, restringe los permisos del archivo (chmod 600 .env) en el host.