entraadm-mcp

Inglés | 日本語

Servidor MCP para el triaje de inicios de sesión y registros de auditoría de Microsoft Entra ID. Solo lectura.

Por qué esto en lugar del Microsoft MCP Server for Enterprise oficial

Microsoft ofrece un MCP Server for Enterprise oficial para datos de Entra ID. Es una buena opción para un administrador interactivo frente a un teclado, y no es adecuado para un bot de triaje desatendido:

• Solo autenticación delegada. El servidor oficial no admite autenticación solo de aplicación (credenciales de cliente), por lo que no puede ejecutarse sin supervisión detrás de una cuenta de servicio. entraadm-mcp está diseñado para ese caso: solo aplicación en producción, con un respaldo delegado (az login) para el desarrollo local.

• Una herramienta de consulta Graph de propósito general, no un conjunto fijo de herramientas. El servidor oficial expone una herramienta que permite al modelo construir llamadas arbitrarias GET/descubrimiento de esquema contra Microsoft Graph. Eso es flexible para un humano, pero incómodo de poner detrás de una lista de permitidos para un perfil de triaje automatizado. entraadm-mcp expone siete herramientas fijas de solo lectura en su lugar.

• Sin traducción de AADSTS. Los fallos de inicio de sesión se devuelven como códigos de error sin procesar; el triaje aún necesita una tabla de búsqueda. entraadm-mcp anota cada fallo de inicio de sesión con lo que el código realmente significa.

• Sin agregación entre solicitudes. Microsoft Graph en sí no puede filtrar inicios de sesión por status/errorCode en el servidor, y no tiene una vista integrada de rociado de contraseñas. signin_failure_stats agrega en el cliente y marca IPs con inicios de sesión fallidos contra muchos usuarios distintos: el patrón que el bloqueo inteligente por cuenta de Entra no detecta por sí solo.

Related MCP server: Microsoft Graph MCP Server

Herramientas

Cada herramienta es de solo lectura. Las operaciones de escritura (desbloquear una cuenta, restablecer una contraseña, revocar una sesión) están fuera del alcance de este servidor.

Modelo de autenticación

Dos modos de autenticación, seleccionados por qué variables de entorno están establecidas:

Establecer una o dos de las tres variables de solo aplicación es un error de configuración y el servidor se niega a iniciar, en lugar de volver silenciosamente a un modo de autenticación diferente al previsto.

Permisos de Graph requeridos

Un permiso faltante nunca bloquea una herramienta. Degrada esa herramienta (o ese campo) a {"error": "...", "missing_permission": "..."} con una explicación legible de qué rol o permiso se necesita, para que health_check y todas las demás herramientas sigan siendo utilizables incluso antes de que se otorguen los permisos completos.

Instalación

uv tool install entraadm-mcp
# or
pip install entraadm-mcp

Configuración

Establece las tres variables de solo aplicación para uso en producción/desatendido:

export ENTRAADM_TENANT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_SECRET=your-client-secret

O deja las tres sin establecer y ejecuta az login primero para el desarrollo local.

Opcional:

# Default page cap for the log-scanning tools (1-50, default 5).
export ENTRAADM_MAX_PAGES_DEFAULT=5

Uso

Claude Code (plugin)

/plugin marketplace add shigechika/entraadm-mcp
/plugin install entraadm-mcp@entraadm-mcp

Claude Code (manual)

Añade a .mcp.json:

{
  "mcpServers": {
    "entraadm-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["entraadm-mcp"],
      "env": {
        "ENTRAADM_TENANT_ID": "${ENTRAADM_TENANT_ID:-}",
        "ENTRAADM_CLIENT_ID": "${ENTRAADM_CLIENT_ID:-}",
        "ENTRAADM_CLIENT_SECRET": "${ENTRAADM_CLIENT_SECRET:-}"
      }
    }
  }
}

Ejecución directa

entraadm-mcp

Opciones de CLI

Notas

• Contrato de cobertura. Cada resultado que recorre una colección paginada de Graph lleva un booleano capped cuando su ventana no se escaneó por completo: un escaneo parcial nunca se informa como si fuera exhaustivo.

• found: false no es un error. get_user y get_user_auth_methods responden a una cuenta inexistente con {"found": false, ...}, no con una clave error: un userPrincipalName mal escrito nunca debería parecer que este servidor está roto.

• Retención. Entra ID P1 retiene los registros de inicio de sesión y de auditoría de directorio durante 30 días. Una ventana más allá de eso devuelve un resultado vacío, no un error.

Desarrollo

uv sync --dev
uv run pytest -v
uv run ruff check .
uv run ruff format --check .

Prueba de humo en vivo

uv run python scripts/smoke_test.py

Solo lectura, sin cargas útiles impresas (solo nombres de herramientas/estados/recuentos de filas) y acotado (ventanas explícitas pequeñas/límites de página): nada aquí escribe en el inquilino ni escanea más de un día de registros.

Publicación

Este repositorio utiliza release-please impulsado por Conventional Commits. Fusiona un PR feat:/fix: a main, y release-please abre (o actualiza) un PR de lanzamiento; fusionar ese PR etiqueta un lanzamiento y activa el pipeline de publicación (PyPI, MCP Registry).

Licencia

MIT