EntraID MCP Server

Servidor MCP de EntraID (Microsoft Graph FastMCP)

Este proyecto proporciona un servidor FastMCP modular y orientado a recursos para interactuar con la API de Microsoft Graph. Está diseñado para ofrecer extensibilidad, facilidad de mantenimiento y seguridad, y admite consultas avanzadas de usuarios, registros de inicio de sesión, estado de MFA y usuarios con privilegios.

Características

• Estructura de recursos modular:
  • Cada recurso (usuarios, registros de inicio de sesión, MFA, etc.) se implementa en su propio módulo en src/msgraph_mcp_server/resources/ .
  • Fácil de ampliar con nuevos recursos (por ejemplo, grupos, dispositivos).
• Cliente de gráficos centralizado:
  • Maneja la autenticación y la inicialización del cliente.
  • Compartido por todos los módulos de recursos.
• Operaciones de usuario integrales:
  • Buscar usuarios por nombre/correo electrónico.
  • Obtener usuario por ID.
  • Enumere todos los usuarios privilegiados (miembros del rol de directorio).
• Gestión completa del ciclo de vida del grupo y de las membresías:
  • Crear, leer, actualizar y eliminar grupos.
  • Agregar o eliminar miembros y propietarios del grupo.
  • Busque y enumere grupos y miembros de grupos.
• Gestión de principales de aplicaciones y servicios:
  • Enumerar, crear, actualizar y eliminar aplicaciones (registros de aplicaciones).
  • Enumerar, crear, actualizar y eliminar entidades de servicio.
  • Vea las asignaciones de roles de la aplicación y los permisos delegados tanto para las aplicaciones como para los principales de servicio.
• Operaciones del registro de inicio de sesión:
  • Consultar los registros de inicio de sesión de un usuario durante los últimos X días.
• Operaciones del MFA:
  • Obtener el estado de MFA para un usuario.
  • Obtenga el estado MFA para todos los miembros de un grupo.
• Gestión de contraseñas:
  • Restablezca las contraseñas de usuario directamente con contraseñas seguras personalizadas o generadas automáticamente.
  • Opción para requerir cambio de contraseña en el próximo inicio de sesión.
• Asistente de permisos:
  • Sugerir permisos adecuados de Microsoft Graph para tareas comunes.
  • Busque y explore los permisos de gráficos disponibles.
  • Ayuda a implementar el principio del mínimo privilegio al recomendar solo los permisos necesarios.
• Manejo y registro de errores:
  • Manejo de errores consistente e informes de progreso a través del contexto FastMCP.
  • Registro detallado para resolución de problemas.
• Seguridad:
  • Los archivos .env y secret están excluidos del control de versiones.
  • Utiliza las mejores prácticas de Microsoft para la autenticación.

Estructura del proyecto

Uso

1. Configuración

• Clonar el repositorio.
• Cree un archivo config/.env con sus credenciales de Azure AD:
  TENANT_ID=your-tenant-id CLIENT_ID=your-client-id CLIENT_SECRET=your-client-secret
• (Opcional) Configure la autenticación basada en certificados si es necesario.

2. Pruebas y desarrollo

Puede probar y desarrollar su servidor MCP directamente utilizando la CLI de FastMCP:

Esto inicia un entorno de desarrollo interactivo con el Inspector MCP. Para más información y uso avanzado, consulte la documentación de FastMCP .

3. Herramientas disponibles

Herramientas de usuario

• search_users(query, ctx, limit=10) — Buscar usuarios por nombre/correo electrónico
• get_user_by_id(user_id, ctx) — Obtener detalles del usuario por ID
• get_privileged_users(ctx) : enumera todos los usuarios en roles de directorio privilegiados
• get_user_roles(user_id, ctx) — Obtener todos los roles de directorio asignados a un usuario
• get_user_groups(user_id, ctx) — Obtener todos los grupos (incluidas las membresías transitivas) para un usuario

Herramientas de grupo

• get_all_groups(ctx, limit=100) — Obtener todos los grupos (con paginación)
• get_group_by_id(group_id, ctx) — Obtener un grupo específico por su ID
• search_groups_by_name(name, ctx, limit=50) — Busca grupos por nombre para mostrar
• get_group_members(group_id, ctx, limit=100) — Obtener los miembros de un grupo por ID de grupo
• create_group(ctx, group_data) — Crea un nuevo grupo (ver a continuación los campos group_data)
• update_group(group_id, ctx, group_data) — Actualizar un grupo existente (campos: displayName, mailNickname, descripción, visibilidad)
• delete_group(group_id, ctx) — Eliminar un grupo por su ID
• add_group_member(group_id, member_id, ctx) — Agregar un miembro (usuario, grupo, dispositivo, etc.) a un grupo
• remove_group_member(group_id, member_id, ctx) — Eliminar un miembro de un grupo
• add_group_owner(group_id, owner_id, ctx) — Agregar un propietario a un grupo
• remove_group_owner(group_id, owner_id, ctx) — Eliminar un propietario de un grupo

Ejemplo de creación/actualización de grupo:

• group_data para create_group y update_group debe ser un diccionario con claves como:
  • displayName (obligatorio para crear)
  • mailNickname (requerido para crear)
  • description (opcional)
  • groupTypes (opcional, p. ej., ["Unified"] )
  • mailEnabled (opcional)
  • securityEnabled (opcional)
  • visibility (opcional, "Privada" o "Pública")
  • owners (opcional, lista de ID de usuarios)
  • members (opcional, lista de identificaciones)
  • membershipRule (obligatorio para grupos dinámicos)
  • membershipRuleProcessingState (opcional, "Activado" o "En pausa")

Consulte las cadenas de documentación groups.py para obtener más detalles sobre los campos y comportamientos admitidos.

Herramientas de registro de inicio de sesión

• get_user_sign_ins(user_id, ctx, days=7) — Obtener los registros de inicio de sesión de un usuario

Herramientas MFA

• get_user_mfa_status(user_id, ctx) — Obtener el estado de MFA para un usuario
• get_group_mfa_status(group_id, ctx) — Obtener el estado de MFA para todos los miembros del grupo

Herramientas del dispositivo

• get_all_managed_devices(filter_os=None) — Obtener todos los dispositivos administrados (opcionalmente filtrar por sistema operativo)
• get_managed_devices_by_user(user_id) — Obtener todos los dispositivos administrados para un usuario específico

Herramientas de política de acceso condicional

• get_conditional_access_policies(ctx) — Obtener todas las políticas de acceso condicional
• get_conditional_access_policy_by_id(policy_id, ctx) — Obtener una única política de acceso condicional por su ID

Herramientas de registro de auditoría

• get_user_audit_logs(user_id, days=30) — Obtener todos los registros de auditoría de directorio relevantes para un usuario por user_id dentro de los últimos N días

Herramientas de gestión de contraseñas

• reset_user_password_direct(user_id, password=None, require_change_on_next_sign_in=True, generate_password=False, password_length=12) — Restablecer la contraseña de un usuario con un valor de contraseña específico o generar una contraseña aleatoria segura

Herramientas auxiliares de permisos

• suggest_permissions_for_task(task_category, task_name) — Sugiera permisos de Microsoft Graph para una tarea específica según asignaciones comunes
• list_permission_categories_and_tasks() — Enumera todas las categorías y tareas disponibles para sugerencias de permisos
• get_all_graph_permissions() — Obtener todos los permisos de Microsoft Graph directamente desde la API de Microsoft Graph
• search_permissions(search_term, permission_type=None) — Busca permisos de Microsoft Graph por palabra clave

Herramientas de aplicación

• list_applications(ctx, limit=100) — Enumera todas las aplicaciones (registros de aplicaciones) en el inquilino, con paginación
• get_application_by_id(app_id, ctx) : obtiene una aplicación específica por su ID de objeto (incluye asignaciones de roles de la aplicación y permisos delegados)
• create_application(ctx, app_data) : crea una nueva aplicación (ver a continuación los campos app_data)
• update_application(app_id, ctx, app_data) : actualiza una aplicación existente (campos: displayName, signInAudience, tags, identifierUris, web, api, requiredResourceAccess)
• delete_application(app_id, ctx) — Eliminar una aplicación por su ID de objeto

Ejemplo de creación/actualización de aplicaciones:

• app_data para create_application y update_application debe ser un diccionario con claves como:
  • displayName (obligatorio para crear)
  • signInAudience (opcional)
  • tags (opcional)
  • identifierUris (opcional)
  • web (opcional)
  • api (opcional)
  • requiredResourceAccess (opcional)

Herramientas principales de servicio

• list_service_principals(ctx, limit=100) — Enumera todos los principales de servicio en el inquilino, con paginación
• get_service_principal_by_id(sp_id, ctx) : obtiene un principal de servicio específico por su ID de objeto (incluye asignaciones de roles de la aplicación y permisos delegados)
• create_service_principal(ctx, sp_data) : crea un nuevo principal de servicio (ver a continuación los campos sp_data)
• update_service_principal(sp_id, ctx, sp_data) : actualiza una entidad de servicio existente (campos: displayName, accountEnabled, tags, appRoleAssignmentRequired)
• delete_service_principal(sp_id, ctx) : elimina un principal de servicio por su ID de objeto

Ejemplo de creación/actualización de entidad de servicio:

• sp_data para create_service_principal y update_service_principal debe ser un diccionario con claves como:
  • appId (requerido para crear)
  • accountEnabled (opcional)
  • tags (opcional)
  • appRoleAssignmentRequired (opcional)
  • displayName (opcional)

Recurso de ejemplo

• greeting://{name} — Devuelve un saludo personalizado

Ampliación del servidor

• Agregue nuevos módulos de recursos en resources/ (por ejemplo, groups.py , devices.py ).
• Registre nuevas herramientas en server.py usando el decorador FastMCP @mcp.tool() .
• Utilice el GraphClient compartido para todas las llamadas API.

Seguridad y mejores prácticas

• Nunca confirme secretos: .env y otros archivos confidenciales son ignorados.
• Usar el mínimo privilegio: otorgue solo los permisos necesarios de Microsoft Graph a su aplicación de Azure AD.
• Auditoría y monitorización: utilice la salida del registro para solucionar problemas y realizar monitorización.

Permisos requeridos de Graph API

Nota: Group.ReadWrite.All es necesario para crear, actualizar y eliminar grupos, así como para agregar o eliminar miembros o propietarios. Group.Read.All y GroupMember.Read.All son suficientes para consultas de solo lectura de grupos y miembros.

Avanzado: Uso con Claude o Cursor

Usando con Claude (Antrópico)

Para instalar y ejecutar este servidor como una herramienta Claude MCP, utilice:

• Reemplace /path/to/ con la ruta de su proyecto actual.
• El indicador -f apunta a su archivo .env (¡nunca confirme secretos!).

Uso con cursor

Agregue lo siguiente a su .cursor/mcp.json ( no incluya secretos reales en el control de versiones):

• Reemplace /path/to/ y las variables de entorno con sus valores reales.
• ¡Nunca guardes secretos reales en tu repositorio!

Licencia

Instituto Tecnológico de Massachusetts (MIT)