EntraID MCP Server (Microsoft Graph FastMCP)

Este proyecto proporciona un servidor FastMCP modular y orientado a recursos para interactuar con Microsoft Graph API. Está diseñado para ser extensible, mantenible y seguro, soportando consultas avanzadas para usuarios, registros de inicio de sesión, estado MFA y usuarios privilegiados.

Características

• Estructura modular de recursos
  • Cada recurso (usuarios, registros de inicio de sesión, MFA, etc.) se implementa en su propio módulo bajo src/msgraph_mcp_server/resources/.
  • Fácil de ampliar con nuevos recursos (por ejemplo, grupos, dispositivos).
• Cliente gráfico centralizado
  • Maneja la autenticación y la inicialización del cliente.
  • Compartido por todos los módulos de recursos.
• Operaciones de usuario completas
  • Búsqueda de usuarios por nombre/correo electrónico.
  • Obtener usuario por ID.
  • Listar todos los usuarios privilegiados (miembros del rol de directorio).
• Gestión completa del ciclo de vida y la pertenencia a grupos
  • Crear, leer, actualizar y eliminar grupos.
  • Añadir/eliminar miembros y propietarios de grupos.
  • Buscar y listar grupos y miembros de grupos.
• Gestión de aplicaciones y servicios principales
  • Enumerar, crear, actualizar y eliminar aplicaciones (registros de aplicaciones).
  • Enumerar, crear, actualizar y eliminar service principals.
  • Ver asignaciones de roles de aplicaciones y permisos delegados tanto para aplicaciones como para principales de servicio.
• Operaciones de registro de inicio de sesión
  • Consultar los registros de inicio de sesión de un usuario durante los últimos X días.
• Operaciones MFA
  • Obtener el estado de MFA de un usuario.
  • Obtener el estado de MFA de todos los miembros de un grupo.
• Gestión de contraseñas
  • Restablezca las contraseñas de los usuarios directamente con contraseñas seguras personalizadas o generadas automáticamente.
  • Opción de solicitar el cambio de contraseña en el siguiente inicio de sesión.
• Ayudante de permisos
  • Sugiere permisos de Microsoft Graph apropiados para tareas comunes.
  • Busca y explora los permisos Graph disponibles.
  • Ayuda a implementar el principio de mínimo privilegio recomendando sólo los permisos necesarios.
• Gestión y registro de errores
  • Gestión coherente de errores e informes de progreso a través del contexto FastMCP.
  • Registro detallado para la 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

src/msgraph_mcp_server/ ├── auth/ # Lógica de autenticación (GraphAuthManager) ├── resources/ # Módulos de recursos (users, signin_logs, mfa, ...) │ ├── users.py # Operaciones con usuarios (buscar, obtener por ID, etc.) │ ├── signin_logs.py # Operaciones con registros de inicio de sesión │ ├── mfa.py # Operaciones de estado de MFA │ ├── permissions_helper.py # Graph permissions utilities and suggestions │ ├── applications.py # Operaciones de aplicación (registro de app) │ ├── service_principals.py # Operaciones de service principal │ └── ...                 # Otros módulos de recursos ├── utils/ # Core GraphClient y otra herramienta de ultilidades, como generador de contraseñas.. ├── server.py # Punto de entrada al servidor FastMCP (registra herramientas/recursos) ├── __init__.py # Marcador del paquete

Uso

1. Configurar

• Clona el repo.
• Crea un archivo config/.env con tus 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 FastMCP:

fastmcp dev '/ruta/para/src/msgraph_mcp_server/server.py'

Esto lanza 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) - Busca usuarios por nombre/email
• get_user_by_id(user_id, ctx) - Obtener detalles de usuario por ID
• get_privileged_users(ctx) - Lista todos los usuarios con roles privilegiados en el directorio
• get_user_roles(user_id, ctx) - Obtener todos los roles de directorio asignados a un usuario
• get_user_groups(user_id, ctx) - Obtiene todos los grupos (incluyendo membresías transitivas) de 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) - Buscar grupos por el nombre mostrado
• get_group_members(group_id, ctx, limit=100) - Obtener los miembros de un grupo por su ID
• create_group(ctx, group_data) - Crear un nuevo grupo (ver más abajo los campos de group_data)
• update_group(group_id, ctx, group_data) - Actualizar un grupo existente (campos: displayName, mailNickname, description, visibility)
• delete_group(group_id, ctx) - Eliminar un grupo por su ID
• add_group_member(group_id, member_id, ctx) - Añadir 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) - Añadir 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 grupos:

• group_data para create_group y update_group debe ser un diccionario con claves como
  • displayName (obligatorio para create)
  • mailNickname (obligatorio para crear)
  • description (opcional)
  • groupTypes (opcional, por ejemplo, ["Unified"])
  • mailEnabled (opcional)
  • securityEnabled (opcional)
  • visibility (opcional, "Private" o "Public")
  • owners (opcional, lista de ID de usuario)
  • members (opcional, lista de ID)
  • membershipRule (obligatorio para grupos dinámicos)
  • membershipRuleProcessingState (opcional, "On" o "Paused")

Consulta la documentación de groups.py para obtener más información 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 de un usuario
• get_group_mfa_status(group_id, ctx) - Obtener el estado de MFA de todos los miembros del grupo

Herramientas de Dispositivo

• get_all_managed_devices(filter_os=None) - Obtener todos los dispositivos gestionados (opcionalmente filtrar por SO)
• get_managed_devices_by_user(user_id) - Obtener todos los dispositivos gestionados 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 en 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 de ayuda para permisos

• suggest_permissions_for_task(task_category, task_name) - Sugerir permisos de Microsoft Graph para una tarea específica basándose en asignaciones comunes
• list_permission_categories_and_tasks() - Lista todas las categorías y tareas disponibles para las sugerencias de permisos
• get_all_graph_permissions() - Obtener todos los permisos de Microsoft Graph directamente de la API de Microsoft Graph
• search_permissions(search_term, permission_type=None) - Buscar permisos de Microsoft Graph por palabra clave

Herramientas de aplicación

• list_applications(ctx, limit=100) - Lista todas las aplicaciones (registros de aplicaciones) en el tenant, con paginación
• get_application_by_id(app_id, ctx) - Obtener una aplicación específica por su ID de objeto (incluye asignaciones de rol de aplicación y permisos delegados)
• create_application(ctx, app_data) - Crear una nueva aplicación (ver más abajo los campos app_data)
• update_application(app_id, ctx, app_data) - Actualizar 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 create)
  • signInAudience (opcional)
  • tags (opcional)
  • identifierUris (opcional)
  • web (opcional)
  • api (opcional)
  • requiredResourceAccess (opcional)

Herramientas de entidad de seguridad

• list_service_principals(ctx, limit=100) - Lista todas las entidades de seguridad del tenant, con paginación
• get_service_principal_by_id(sp_id, ctx) - Obtener una entidad de seguridad de servicio específica por su ID de objeto (incluye asignaciones de rol de aplicación y permisos delegados)
• create_service_principal(ctx, sp_data) - Crear una nueva entidad de seguridad de servicio (véanse a continuación los campos de sp_data)
• update_service_principal(sp_id, ctx, sp_data) - Actualiza una entidad de seguridad existente (campos: displayName, accountEnabled, tags, appRoleAssignmentRequired)
• delete_service_principal(sp_id, ctx) - Eliminar una entidad de seguridad por su ID de objeto

Ejemplo de creación/actualización de una entidad de seguridad:

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

Ejemplo de recurso

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

Ampliación del servidor

• Añade nuevos módulos de recursos en resources/ (por ejemplo, groups.py, devices.py).
• Registra nuevas herramientas en server.py usando el decorador FastMCP @mcp.tool().
• Utiliza el GraphClient compartido para todas las llamadas a la API.

Seguridad y buenas prácticas

• Nunca confirmar secretos:.env y otros archivos sensibles son gitignored.
• Utiliza el mínimo privilegio: Conceda sólo los permisos de Microsoft Graph necesarios a su aplicación Azure AD.
• Auditoría y supervisión: Utilice la salida de registro para la solución de problemas y la supervisión.

Permisos requeridos de Graph API

Nota:Group.ReadWrite.All es necesario para crear, actualizar y eliminar grupos, así como para añadir o eliminar miembros o propietarios de grupos. Group.Read.All y GroupMember.Read.All son suficientes para las consultas de grupos y miembros de sólo lectura.

Avanzado: Utilización con Claude o Cursor

Uso con Claude (Anthropic)

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

fastmcp install '/ruta/para/src/msgraph_mcp_server/server.py' \ --con msgraph-sdk --con azure-identity --con azure-core --con msgraph-core \ -f /ruta/para/.env

• Sustituya /ruta/a/ por la ruta real de su proyecto.
• La bandera -f apunta a tu archivo .env (¡nunca confirmes secretos!).

Uso con Cursor

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

{ "EntraID MCP Server": { "command": "uv", "args": [ "run", "--with", "azure-core", "--with", "azure-identity", "--with", "fastmcp", "--with", "msgraph-core", "--with", "msgraph-sdk", "fastmcp", "run", "/path/to/src/msgraph_mcp_server/server.py" ], "env": { "TENANT_ID": "<your-tenant-id>", "CLIENT_ID": "<su-id-cliente>", "CLIENT_SECRET": "<secretadelcliente>" } } }

• Sustituye /path/to/ y las variables de entorno por tus valores reales.
• ¡Nunca envíe secretos reales a su repositorio!

Licencia

MIT