Microsoft Entra ID MCP Server

Un servidor MCP en Python para operaciones de directorio, usuario, grupo, dispositivo, inicio de sesión y seguridad de Microsoft Entra ID (Azure AD) a través de Microsoft Graph.

GitHub
41
Prueba este MCPPatrocinado

Documentación

EntraID MCP Server (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 la extensibilidad, mantenibilidad y seguridad, admitiendo consultas avanzadas para usuarios, registros de inicio de sesión, estado de MFA y usuarios privilegiados.

Características

  • Estructura de recursos modular:
    • 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 extender con nuevos recursos (por ejemplo, grupos, dispositivos).
  • Cliente Graph centralizado:
    • Maneja la autenticación y la inicialización del cliente.
    • Compartido por todos los módulos de recursos.
  • Operaciones integrales de usuario:
    • Buscar usuarios por nombre/correo electrónico.
    • Obtener usuario por ID.
    • Listar todos los usuarios privilegiados (miembros de roles de directorio).
  • Gestión completa del ciclo de vida de grupos y membresías:
    • Crear, leer, actualizar y eliminar grupos.
    • Agregar/eliminar miembros y propietarios de grupos.
    • Buscar y listar grupos y miembros de grupos.
  • Gestión de aplicaciones y entidades de servicio:
    • Listar, crear, actualizar y eliminar aplicaciones (registros de aplicaciones).
    • Listar, crear, actualizar y eliminar entidades de servicio.
    • Ver asignaciones de roles de aplicación y permisos delegados tanto para aplicaciones como para entidades de servicio.
  • Operaciones de registros de inicio de sesión:
    • Consultar registros de inicio de sesión de un usuario de los últimos X días.
  • Operaciones de 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:
    • Restablecer contraseñas de usuarios directamente con contraseñas seguras personalizadas o generadas automáticamente.
    • Opción para exigir cambio de contraseña en el próximo inicio de sesión.
  • Asistente de permisos:
    • Sugerir permisos apropiados de Microsoft Graph para tareas comunes.
    • Buscar y explorar permisos de Graph disponibles.
    • Ayuda a implementar el principio de mínimo privilegio recomendando solo los permisos necesarios.
  • Manejo de errores y registro:
    • Manejo de errores consistente e informes de progreso a través del contexto de FastMCP.
    • Registro detallado para la resolución de problemas.
  • Seguridad:
    • .env y los archivos secretos 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/           # Authentication logic (GraphAuthManager)
├── resources/      # Resource modules (users, signin_logs, mfa, ...)
│   ├── users.py            # User operations (search, get by ID, etc.)
│   ├── signin_logs.py      # Sign-in log operations
│   ├── mfa.py              # MFA status operations
│   ├── permissions_helper.py # Graph permissions utilities and suggestions
│   ├── applications.py       # Application (app registration) operations
│   ├── service_principals.py # Service principal operations
│   └── ...                 # Other resource modules
├── utils/          # Core GraphClient and other ultilities tool, such as password generator..
├── server.py       # FastMCP server entry point (registers tools/resources)
├── __init__.py     # Package marker

Uso

1. Configuración

  • Clona el repositorio.
  • 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) Configura la autenticación basada en certificados si es necesario.

2. Pruebas y desarrollo

Puedes probar y desarrollar tu servidor MCP directamente usando la CLI de FastMCP:

fastmcp dev '/path/to/src/msgraph_mcp_server/server.py'

Esto lanza un entorno de desarrollo interactivo con el MCP Inspector. Para más información y uso avanzado, consulta 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) — Listar 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) 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 nombre para mostrar
  • get_group_members(group_id, ctx, limit=100) — Obtener miembros de un grupo por ID de grupo
  • create_group(ctx, group_data) — Crear un nuevo grupo (consulta a continuación 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) — 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 (requerido para crear)
    • mailNickname (requerido para crear)
    • description (opcional)
    • groupTypes (opcional, por ejemplo, ["Unified"])
    • mailEnabled (opcional)
    • securityEnabled (opcional)
    • visibility (opcional, "Private" o "Public")
    • owners (opcional, lista de IDs de usuario)
    • members (opcional, lista de IDs)
    • membershipRule (requerido para grupos dinámicos)
    • membershipRuleProcessingState (opcional, "On" o "Paused")

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

Herramientas de registros de inicio de sesión

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

Herramientas de 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 dispositivos

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

Herramientas de políticas 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 política de acceso condicional por su ID

Herramientas de registros de auditoría

  • get_user_audit_logs(user_id, days=30) — Obtener todos los registros de auditoría de directorio relevantes de 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 específico o generar una contraseña aleatoria segura

Herramientas de asistente de permisos

  • suggest_permissions_for_task(task_category, task_name) — Sugerir permisos de Microsoft Graph para una tarea específica según asignaciones comunes
  • list_permission_categories_and_tasks() — Listar 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) — Buscar permisos de Microsoft Graph por palabra clave

Herramientas de aplicaciones

  • list_applications(ctx, limit=100) — Listar todas las aplicaciones (registros de aplicaciones) en el inquilino, con paginación
  • get_application_by_id(app_id, ctx) — Obtener una aplicación específica por su ID de objeto (incluye asignaciones de roles de aplicación y permisos delegados)
  • create_application(ctx, app_data) — Crear una nueva aplicación (consulta a continuación los campos de 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 aplicación:

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

Herramientas de entidades de servicio

  • list_service_principals(ctx, limit=100) — Listar todas las entidades de servicio en el inquilino, con paginación
  • get_service_principal_by_id(sp_id, ctx) — Obtener una entidad de servicio específica por su ID de objeto (incluye asignaciones de roles de aplicación y permisos delegados)
  • create_service_principal(ctx, sp_data) — Crear una nueva entidad de servicio (consulta a continuación los campos de sp_data)
  • update_service_principal(sp_id, ctx, sp_data) — Actualizar una entidad de servicio existente (campos: displayName, accountEnabled, tags, appRoleAssignmentRequired)
  • delete_service_principal(sp_id, ctx) — Eliminar una entidad 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

Extensión del servidor

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

Seguridad y mejores prácticas

  • Nunca confirmes secretos: .env y otros archivos sensibles están en gitignore.
  • Usa el mínimo privilegio: Otorga solo los permisos necesarios de Microsoft Graph a tu aplicación de Azure AD.
  • Audita y monitorea: Usa la salida de registro para la resolución de problemas y el monitoreo.

Permisos requeridos de Graph API

API / PermissionTypeDescription
AuditLog.Read.AllApplicationLeer todos los datos de registros de auditoría
AuthenticationContext.Read.AllApplicationLeer toda la información de contexto de autenticación
DeviceManagementManagedDevices.Read.AllApplicationLeer dispositivos de Microsoft Intune
Directory.Read.AllApplicationLeer datos de directorio
Group.Read.AllApplicationLeer todos los grupos
GroupMember.Read.AllApplicationLeer todas las membresías de grupo
Group.ReadWrite.AllApplicationCrear, actualizar, eliminar grupos; gestionar miembros y propietarios de grupos
Policy.Read.AllApplicationLeer las políticas de tu organización
RoleManagement.Read.DirectoryApplicationLeer todos los ajustes de RBAC del directorio
User.Read.AllApplicationLeer los perfiles completos de todos los usuarios
User-PasswordProfile.ReadWrite.AllApplicationPermiso de mínimo privilegio para actualizar la propiedad passwordProfile
UserAuthenticationMethod.Read.AllApplicationLeer todos los métodos de autenticación de los usuarios
Application.ReadWrite.AllApplicationCrear, actualizar y eliminar aplicaciones (registros de aplicaciones) y entidades de servicio

Nota: Group.ReadWrite.All es necesario para la creación, actualización y eliminación de grupos, y para agregar/eliminar miembros o propietarios de grupos. Group.Read.All y GroupMember.Read.All son suficientes para consultas de solo lectura de grupos y membresías.

Avanzado: Uso con Claude o Cursor

Uso con Claude (Anthropic)

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

fastmcp install '/path/to/src/msgraph_mcp_server/server.py' \
  --with msgraph-sdk --with azure-identity --with azure-core --with msgraph-core \
  -f /path/to/.env
  • Reemplaza /path/to/ con la ruta real de tu proyecto.
  • La bandera -f apunta a tu archivo .env (¡nunca confirmes secretos!).

Uso con Cursor

Agrega lo siguiente a tu .cursor/mcp.json (no incluyas 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": "<your-client-id>",
      "CLIENT_SECRET": "<your-client-secret>"
    }
  }
}
  • Reemplaza /path/to/ y las variables de entorno con tus valores reales.
  • ¡Nunca confirmes secretos reales en tu repositorio!

Licencia

MIT