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.

Related MCP server: ms-365-admin-mcp-server

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

• 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:

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

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:

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

• 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):

{
  "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>"
    }
  }
}

• 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)