outlook-ews-mcp

outlook-ews-mcp es un servidor MCP para Microsoft Exchange local mediante EWS (exchangelib). Proporciona a clientes compatibles con MCP (Claude Desktop, Claude Code y cualquier otro cliente MCP) acceso a correo, calendario, contactos, carpetas, adjuntos y datos de disponibilidad a través de un único servicio Python comprobable — sin necesidad de scripting directo en el buzón.

Renombrado desde outlook-mcp. Ese nombre ya estaba ocupado en PyPI por un proyecto no relacionado, por lo que el nombre de distribución y CLI ahora es outlook-ews-mcp. La ruta de importación de Python no cambia. Hasta la primera versión etiquetada en PyPI, instale desde este repositorio como se muestra a continuación.

Contenido

• Aspectos destacados

• Catálogo de herramientas

• Casos de uso típicos

• Notas de seguridad

• Inicio rápido

• Configuración

• Cola de solicitudes

• Ejemplo con Claude Desktop

• Comprobación rápida

• Docker

• CI/CD

• Desarrollo

• Notas del proyecto

• Contribuciones

• Licencia

Related MCP server: owa-mail-mcp

Aspectos destacados

• Correo — listar, buscar (subcadena o sintaxis de consulta avanzada), leer, enviar, responder, reenviar, mover, copiar, eliminar, marcar, categorizar, acciones masivas, exportación MIME sin procesar, agregar/eliminar adjuntos

• Sistema — reglas de la bandeja de entrada, fuera de la oficina (respuestas automáticas), listado de delegados de solo lectura

• Calendario — listar, crear, actualizar, eliminar, responder a invitaciones, buscar espacios libres, ver el calendario de un buzón compartido/delegado, Room Finder, acciones masivas

• Contactos — buscar, leer, crear, actualizar, eliminar

• Carpetas y adjuntos — CRUD de carpetas y descarga de adjuntos

• Autenticación — NTLM y Basic contra Exchange local

• Transporte — stdio y SSE

• Arquitectura — mapeo centralizado de errores a través de una única abstracción ExchangeClient (ver Notas del proyecto)

• Seguridad — una comprobación rápida más segura para la privacidad por defecto (ver Comprobación rápida)

• Operaciones — imagen Docker y pipelines de CI/CD para GitHub y GitLab incluidos

Catálogo de herramientas

Cada herramienta a continuación está registrada en tool_specs.py, la única fuente de verdad para su nombre, descripción y esquema. Solo lectura marca las herramientas que nunca modifican el buzón — obtienen más concurrencia (ver Cola de solicitudes) y son seguras de llamar especulativamente.

Sistema

⚠️ create_inbox_rule / update_inbox_rule / delete_inbox_rule gestionan reglas a través de EWS, lo que elimina el blob de reglas del lado del cliente que Outlook de escritorio mantiene — esto puede borrar reglas que un usuario creó en el propio Outlook. Este es un comportamiento documentado de EWS, no un error aquí.

Correo

Calendario

Contactos

Casos de uso típicos

• Conectar Claude Desktop u otro cliente MCP a Exchange local

• Buscar mensajes de la bandeja de entrada y obtener el contenido completo del correo

• Enviar o redactar correos desde flujos de trabajo de IA

• Inspeccionar calendarios y crear reuniones

• Comprobar ventanas de libre/ocupado para programar

• Buscar contactos personales o la Lista de direcciones global

• Exponer operaciones de Exchange a través de un límite MCP controlado en lugar de scripting directo del buzón

Notas de seguridad

Lo que hace el código actual:

Con lo que aún debes tener cuidado:

• EXCHANGE_VERIFY_SSL=false desactiva la verificación de certificados TLS — solo entornos internos/de confianza con certificados autofirmados.

• EXCHANGE_AUTH_TYPE=Basic envía las credenciales en texto plano, por lo que el servidor se niega a iniciar contra un EXCHANGE_SERVER http://; solo anula con EXCHANGE_ALLOW_INSECURE_BASIC_AUTH=true para un servidor local/de prueba que controles.

• get_attachment escribe archivos en el disco, y send_email/reply_email/forward_email/ create_draft leen archivos locales (a través de attachments) y adjuntan su contenido al correo saliente. Combinado con contenido de correo no confiable, esta es una vía plausible para la exfiltración por inyección de prompts de cualquier archivo legible por el proceso. El acceso a archivos locales está denegado por defecto y solo funciona una vez que EXCHANGE_ATTACHMENT_ROOT se establece en un directorio absoluto, que luego confina tanto las rutas de attachments como el save_path de get_attachment a ese árbol de directorios (un save_path no establecido aún cae al directorio temporal del sistema).

• outlook-ews-mcp-smoke es seguro para la privacidad por defecto e imprime solo información de buzón enmascarada más recuentos; establece OUTLOOK_MCP_SMOKE_INCLUDE_DATA=true solo si deseas explícitamente datos reales de bandeja de entrada/eventos en stdout.

• Si habilitas el registro de archivos con LOG_FILE, protege ese archivo con permisos del sistema operativo.

• Si publicas imágenes Docker desde CI, protege el acceso al proyecto de GitLab/GitHub y los permisos del registro.

Inicio rápido

uv venv
source .venv/bin/activate
uv pip install -e .[dev]
cp .env.example .env
outlook-ews-mcp

Por defecto, el servidor se ejecuta en modo stdio. Establece MCP_TRANSPORT=sse para iniciar un servidor HTTP en su lugar.

Configuración

.env mínimo para comenzar — todo lo demás a continuación tiene un valor predeterminado funcional:

EXCHANGE_SERVER=https://mail.company.com/EWS/Exchange.asmx
EXCHANGE_USERNAME=DOMAIN\username
EXCHANGE_PASSWORD=secret
EXCHANGE_EMAIL_ADDRESS=user@company.com
EXCHANGE_AUTH_TYPE=NTLM

Una copia completamente comentada de cada variable está en .env.example.

Notas de comportamiento que no están vinculadas a una sola variable:

• list_events y find_free_slots aceptan un limit acotado (predeterminado 200, máximo 1000); los rangos de eventos están limitados a 366 días y los rangos de espacios libres a 31 días, por lo que las consultas amplias no pueden producir respuestas EWS o MCP ilimitadas.

• Los listados se mantienen ligeros por diseño: los resúmenes de correo incluyen el remitente pero no las listas de destinatarios (get_email las tiene), list_events devuelve eventos sin cuerpos (get_event los tiene), y get_email devuelve cabeceras RFC-822 solo con include_headers: true.

• Las operaciones de envío devuelven id: null cuando EWS no proporciona un id duradero para la copia enviada (notablemente respuestas, reenvíos y borradores enviados).

• Los metadatos de adjuntos incluyen downloadable; los adjuntos de elementos de Exchange incrustados tienen downloadable: false y no pueden guardarse con get_attachment.

Cola de solicitudes

Los clientes emiten varias llamadas a herramientas en paralelo. El trabajo de Exchange es bloqueante, por lo que el servidor lo ejecuta en hilos de trabajo y admite llamadas a través de una única cola FIFO compartida.

• MCP_MAX_CONCURRENCY (predeterminado 4) establece cuántas llamadas de solo lectura se ejecutan a la vez, de modo que un agente que solicita un correo, la lista de carpetas y el calendario paga el viaje de ida y vuelta más lento en lugar de la suma. Las llamadas de mutación siempre se ejecutan de forma exclusiva — una a la vez, nunca superponiéndose a una lectura — por lo que no pueden ocurrir carreras de lectura/escritura en el estado compartido de la cuenta. Los llamadores que superan el límite esperan su turno, atendidos en orden de llegada; una mutación en espera bloquea a las lecturas posteriores para que no la adelanten.

• MCP_MAX_QUEUE_SIZE (predeterminado 20) limita cuántas llamadas pueden admitirse a la vez, en ejecución o en espera. Una vez que ya hay esa cantidad, las llamadas adicionales reciben un error server_busy inmediato en lugar de unirse a una cola ilimitada.

• El transporte permanece receptivo mientras el trabajo está en curso. Las herramientas se esperan en lugar de ejecutarse en el hilo del bucle de eventos, por lo que las respuestas terminadas salen inmediatamente y los pings se responden mientras una llamada larga aún se está ejecutando.

• No hay tiempo de espera por llamada, deliberadamente. Un hilo bloqueado en una lectura de socket no puede ser eliminado desde fuera; el runtime solo puede dejar de esperar por él, lo que abandona el hilo junto con la sesión EWS que mantiene. El grupo de sesiones de exchangelib tiene un máximo estricto y entrega sesiones en un bucle sin ruta de rendición, por lo que las sesiones filtradas eventualmente lo agotan y cada llamada posterior se bloquea para siempre. En su lugar, se espera a que una llamada lenta termine, limitada por EXCHANGE_TIMEOUT más EXCHANGE_MAX_RETRY_WAIT_SECONDS: la política de reintentos de la cuenta es de fallo rápido, por lo que cada llamada EWS lanza un error en su primer error transitorio en lugar de que exchangelib la reintente internamente para siempre, y ExchangeClient reintenta solo llamadas de solo lectura, limitadas por ese presupuesto de tiempo real. Las escrituras nunca se reintentan automáticamente. Los excesos más allá del presupuesto esperado se registran.

Ejemplo de Claude Desktop

{
  "mcpServers": {
    "outlook": {
      "command": "outlook-ews-mcp",
      "env": {
        "EXCHANGE_SERVER": "https://mail.company.com/EWS/Exchange.asmx",
        "EXCHANGE_USERNAME": "DOMAIN\\username",
        "EXCHANGE_PASSWORD": "secret",
        "EXCHANGE_EMAIL_ADDRESS": "user@company.com",
        "EXCHANGE_AUTH_TYPE": "NTLM"
      }
    }
  }
}

Prueba de humo

Después de completar .env, ejecuta:

outlook-ews-mcp-smoke

La salida predeterminada está saneada para una verificación más segura. Si quieres intencionalmente datos de muestra de buzón/eventos en la salida:

OUTLOOK_MCP_SMOKE_INCLUDE_DATA=true outlook-ews-mcp-smoke

Docker

docker build -t outlook-ews-mcp .
docker run --rm --env-file .env outlook-ews-mcp

CI/CD

GitHub Actions y GitLab CI ejecutan lint, formato, comprobaciones de tipos, pruebas, auditoría de dependencias y compilaciones de paquetes, usando la versión de uv fijada en pyproject.toml.

Comportamiento predeterminado de etiquetado de imágenes:

Desarrollo

uv run --python 3.12 --with '.[dev]' ruff check .
uv run --python 3.12 --with '.[dev]' pytest -q

Notas del proyecto

• La implementación se centra en una única abstracción ExchangeClient para que la autenticación, el transporte, los reintentos y el mapeo de errores permanezcan centralizados.

• Los errores se devuelven en un formato JSON estructurado adecuado para el manejo de MCP isError=true.

Contribuciones

Los informes de errores y las PRs son bienvenidos — consulta CONTRIBUTING.md para saber cómo configurar un entorno de desarrollo y ejecutar la suite de pruebas sin un servidor Exchange real. Para informes de vulnerabilidades, consulta SECURITY.md.

Licencia

MIT — consulta LICENSE.