Jamf Pro MCP Server

Un servidor para gestionar dispositivos Apple a través de la API de Jamf Pro.

GitHub
1

Documentación

Jamf Pro MCP Server

MIT License Node.js Version TypeScript MCP SDK

Un servidor MCP (Model Context Protocol) integral que permite a los asistentes de IA interactuar con Jamf Pro para la gestión completa de dispositivos Apple, incluyendo computadoras, dispositivos móviles, políticas, scripts, perfiles de configuración, paquetes y reportes.

Tests

🚀 Inicio Rápido

# Clone the repository
git clone https://github.com/dbankscard/jamf-mcp-server.git
cd jamf-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configura tus credenciales en Claude Desktop (consulta la sección de Configuración a continuación).

Características

Herramientas (Funciones Ejecutables)

Gestión de Dispositivos

  • searchDevices: Busca dispositivos por nombre, número de serie, dirección IP o nombre de usuario (admite coincidencias parciales)
  • getDeviceDetails: Recupera información completa del dispositivo por ID o nombre
  • checkDeviceCompliance: Encuentra dispositivos que no han reportado en X días (optimizado para flotas grandes)
  • getDevicesBatch: Obtén detalles de múltiples dispositivos de manera eficiente
  • updateInventory: Fuerza la actualización de inventario en dispositivos

Gestión de Políticas

  • listPolicies: Lista todas las políticas en Jamf Pro
  • getPolicyDetails: Obtén información detallada sobre una política específica por ID o nombre (incluye alcance, scripts con contenido completo y paquetes: puedes ver exactamente qué scripts y paquetes están adjuntos a cualquier política)
  • searchPolicies: Busca políticas por nombre o ID (admite coincidencias parciales)
  • executePolicy: Ejecuta políticas en dispositivos específicos (la política y el dispositivo pueden especificarse por ID o nombre, requiere confirmación)

Gestión de Scripts

  • deployScript: Ejecuta scripts para resolución de problemas (con confirmación)
  • getScriptDetails: Obtén el contenido completo del script y metadatos, incluyendo parámetros, notas y requisitos del sistema operativo

Gestión de Perfiles de Configuración

  • listConfigurationProfiles: Lista todos los perfiles de configuración (computadora o dispositivo móvil)
  • getConfigurationProfileDetails: Obtén información detallada sobre un perfil de configuración específico
  • searchConfigurationProfiles: Busca perfiles de configuración por nombre
  • deployConfigurationProfile: Implementa un perfil de configuración en uno o más dispositivos (con confirmación)
  • removeConfigurationProfile: Elimina un perfil de configuración de uno o más dispositivos (con confirmación)

Gestión de Paquetes

  • listPackages: Lista todos los paquetes con nombre, versión, categoría y tamaño
  • getPackageDetails: Obtén información detallada del paquete, incluyendo metadatos, requisitos y notas
  • searchPackages: Busca paquetes por nombre, nombre de archivo o categoría
  • getPackageDeploymentHistory: Obtén el historial de implementación y estadísticas de un paquete
  • getPoliciesUsingPackage: Encuentra todas las políticas que utilizan un paquete específico

Gestión de Grupos de Computadoras

  • listComputerGroups: Lista grupos de computadoras (grupos inteligentes, grupos estáticos o todos)
  • getComputerGroupDetails: Obtén información detallada sobre un grupo específico, incluyendo membresía y criterios de grupos inteligentes
  • searchComputerGroups: Busca grupos de computadoras por nombre
  • getComputerGroupMembers: Obtén todos los miembros de un grupo de computadoras específico
  • createStaticComputerGroup: Crea un nuevo grupo de computadoras estático con miembros especificados (con confirmación)
  • updateStaticComputerGroup: Actualiza la membresía de un grupo de computadoras estático (con confirmación)
  • deleteComputerGroup: Elimina un grupo de computadoras (con confirmación)

Gestión de Dispositivos Móviles

  • searchMobileDevices: Busca dispositivos móviles por nombre, número de serie, UDID u otros criterios
  • getMobileDeviceDetails: Obtén información detallada sobre un dispositivo móvil específico, incluyendo hardware, sistema operativo, batería y estado de gestión
  • listMobileDevices: Lista todos los dispositivos móviles en Jamf Pro con información básica
  • updateMobileDeviceInventory: Fuerza una actualización de inventario en un dispositivo móvil específico
  • sendMDMCommand: Envía comandos MDM a dispositivos móviles (bloquear, borrar, limpiar código de acceso, etc.) con confirmación para acciones destructivas
  • listMobileDeviceGroups: Lista grupos de dispositivos móviles (grupos inteligentes, grupos estáticos o todos)
  • getMobileDeviceGroupDetails: Obtén información detallada sobre un grupo de dispositivos móviles específico, incluyendo membresía y criterios

Recursos (Datos de Solo Lectura)

  • jamf://inventory/computers: Lista paginada de dispositivos
  • jamf://inventory/mobile-devices: Lista paginada de dispositivos móviles
  • jamf://reports/compliance: Reporte de cumplimiento de seguridad y parches
  • jamf://reports/mobile-device-compliance: Reporte de cumplimiento de dispositivos móviles que muestra estado de gestión y problemas
  • jamf://reports/storage: Análisis de uso de disco
  • jamf://reports/os-versions: Desglose de versiones del sistema operativo

Prompts (Plantillas de Flujo de Trabajo)

  • troubleshoot-device: Resolución de problemas de dispositivos paso a paso
  • deploy-software: Flujo de trabajo de implementación de software
  • compliance-check: Reporte integral de cumplimiento
  • mass-update: Operaciones masivas de dispositivos
  • storage-cleanup: Gestión de espacio en disco

Instalación

  1. Clona este repositorio
  2. Instala las dependencias: 
    cd jamf-mcp-server
npm install
  3. Compila el proyecto: 
    npm run build

Configuración

Configuración de Autenticación de la API de Jamf Pro

  1. En Jamf Pro, ve a Configuración > Sistema > Roles y Clientes de API
  2. Crea un nuevo Rol de API con los permisos necesarios
  3. Crea un nuevo Cliente de API:
    • Asigna el Rol de API que creaste
    • Anota el ID de Cliente y genera un Secreto de Cliente
  4. Usa estas credenciales en tus variables de entorno

Configuración de Claude Desktop

Agrega a tu archivo de configuración de Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "jamf-pro": {
      "command": "node",
      "args": ["/absolute/path/to/jamf-mcp-server/dist/index.js"],
      "env": {
        "JAMF_URL": "https://your-instance.jamfcloud.com",
        "JAMF_CLIENT_ID": "your-api-client-id",
        "JAMF_CLIENT_SECRET": "your-api-client-secret",
        "JAMF_READ_ONLY": "false",
        "JAMF_USE_ENHANCED_MODE": "true",
        "JAMF_DEBUG_MODE": "false"
      }
    }
  }
}

Ejemplos de Uso

Nota: La mayoría de las herramientas admiten búsqueda tanto por ID como por nombre. Al buscar por nombre, se admiten coincidencias parciales. Por ejemplo, puedes buscar "Chrome" para encontrar todos los elementos que contengan esa palabra en su nombre.

Buscar un Dispositivo

Can you find John Smith's MacBook?
Search for device GH-IT-0322
Find devices with "Marketing" in the name

Ver Detalles del Dispositivo

Show me the details for device ID 123

Verificar Cumplimiento del Dispositivo (NUEVO - Optimizado)

Show me all devices that haven't reported in 30 days

Esto utilizará la nueva herramienta checkDeviceCompliance que procesa eficientemente todos los dispositivos y proporciona:

  • Estadísticas de resumen (cumplido/no cumplido/desconocido)
  • Dispositivos críticos (90+ días)
  • Dispositivos con advertencia (30-90 días)
  • Lista detallada de dispositivos opcional

Análisis de Políticas - Ver Scripts y Paquetes

What packages are deployed by the 'Software Install' policy?

Show me the scripts that run in the 'Weekly Maintenance' policy

Get full details for policy 'macOS Updates' including all scripts and packages

Gestión de Perfiles de Configuración

List all computer configuration profiles

Search for WiFi configuration profiles

Deploy configuration profile ID 5 to devices 123, 456, and 789

Remove mobile device configuration profile ID 10 from device 999

Operaciones Masivas de Dispositivos (NUEVO)

Get details for devices 123, 456, and 789

Implementar Software

Install Slack on all marketing team Macs

Análisis de Almacenamiento

Which devices have less than 10GB free space?

Operaciones de Políticas (NUEVO)

List all policies
Show me all security-related policies
Get details for policy ID 123
Search for policies containing "update"
Get policy details with full script content

Operaciones de Scripts (NUEVO)

Get the content of script ID 42
Show me what script 123 does
Get policy 456 details including the actual script code

Gestión de Paquetes (NUEVO)

List all packages
Search for packages containing "Office"
Get details for package ID 15
Show me the deployment history for package ID 20
Which policies use package ID 25?
Find all policies that deploy Chrome

Gestión de Grupos de Computadoras (NUEVO)

List all computer groups
Show me only smart groups
Search for groups containing "marketing"
Get details for computer group ID 10
Show me all members of the "Executive Laptops" group
Create a static group called "Project Alpha" with computers 123, 456, and 789
Update the "Deployment Test" group to include computers 111, 222, and 333
Delete computer group ID 99

Gestión de Dispositivos Móviles (NUEVO)

Search for iPads
List all mobile devices
Get details for mobile device ID 456
Search for devices with serial number ABC123
Update inventory for mobile device 789
Lock mobile device 123
Wipe mobile device 456 (requires confirmation)
Clear passcode for device 789 (requires confirmation)
Enable Lost Mode on device 321
List all mobile device groups
Get details for mobile device group ID 15
Show me smart mobile device groups

Comandos MDM Admitidos

Los siguientes comandos MDM son compatibles con dispositivos móviles:

  • DeviceLock: Bloquea el dispositivo inmediatamente
  • EraseDevice: Borra el dispositivo (requiere confirmación)
  • ClearPasscode: Elimina el código de acceso del dispositivo (requiere confirmación)
  • RestartDevice: Reinicia el dispositivo
  • ShutDownDevice: Apaga el dispositivo
  • EnableLostMode: Activa el Modo Perdido
  • DisableLostMode: Desactiva el Modo Perdido
  • PlayLostModeSound: Reproduce un sonido en el dispositivo perdido
  • UpdateInventory: Fuerza la actualización de inventario
  • ClearRestrictionsPassword: Limpia la contraseña de restricciones (requiere confirmación)
  • Comandos de Configuración: Activar/desactivar Bluetooth, WiFi, Roaming de Datos, Roaming de Voz, Punto de Acceso Personal

Características de Seguridad

  • Modo de Solo Lectura: Establece JAMF_READ_ONLY=true para evitar cualquier modificación
  • Confirmación Requerida: Las operaciones destructivas requieren confirmación explícita
  • Manejo de Errores: Mensajes de error completos y recuperación
  • Límite de Velocidad: Respeta los límites de la API de Jamf Pro
  • Registro de Auditoría: Todas las operaciones se registran

Manejo de Errores Mejorado (v1.1.0)

El servidor ahora incluye manejo integral de errores y lógica de reintento:

Características

  • Reintento Automático: Retroceso exponencial para fallos transitorios
  • Interruptor de Circuito: Previene fallos en cascada
  • Mensajes de Error Mejorados: Información detallada de errores con sugerencias accionables
  • Registro de Solicitudes/Respuestas: Modo de depuración para resolución de problemas
  • Límite de Velocidad: Limitador de velocidad integrado para prevenir la limitación de la API

Configuración

Agrega estas variables de entorno opcionales a tu configuración de Claude Desktop:

{
  "env": {
    "JAMF_USE_ENHANCED_MODE": "true",      // Enable enhanced features (default: false)
    "JAMF_MAX_RETRIES": "3",               // Max retry attempts (default: 3)
    "JAMF_RETRY_DELAY": "1000",            // Initial retry delay in ms (default: 1000)
    "JAMF_RETRY_MAX_DELAY": "10000",       // Max retry delay in ms (default: 10000)
    "JAMF_DEBUG_MODE": "false",            // Enable debug logging (default: false)
    "JAMF_ENABLE_RETRY": "true",           // Enable automatic retries (default: true)
    "JAMF_ENABLE_RATE_LIMITING": "false",  // Enable rate limiting (default: false)
    "JAMF_ENABLE_CIRCUIT_BREAKER": "false" // Enable circuit breaker (default: false)
  }
}

Tipos de Error

El modo mejorado proporciona tipos de error específicos con sugerencias útiles:

  • JamfAPIError: Errores generales de API con códigos de estado y sugerencias
  • NetworkError: Problemas de conexión con consejos de solución de problemas de red
  • AuthenticationError: Fallos de autenticación con pasos de verificación de credenciales
  • RateLimitError: Errores de límite de velocidad con tiempos de reintento
  • ValidationError: Errores de validación de entrada con comentarios específicos por campo

Consulta docs/ERROR_HANDLING.md para documentación detallada.

Desarrollo

Configuración de Desarrollo Local

Para desarrollo local sin Claude Desktop, crea un archivo .env:

cp .env.example .env
# Edit .env with your Jamf Pro credentials:
# JAMF_URL=https://your-instance.jamfcloud.com
# JAMF_CLIENT_ID=your-api-client-id
# JAMF_CLIENT_SECRET=your-api-client-secret
# JAMF_READ_ONLY=false

Ejecución en Modo de Desarrollo

npm run dev

Pruebas con MCP Inspector

npm run inspector

Ejecución de Pruebas

npm test

Requisitos de la API

Este servidor requiere:

  • Jamf Pro versión 10.35.0 o posterior
  • Usuario de API con permisos apropiados
  • Acceso de red a tu instancia de Jamf Pro

Permisos de API Recomendados

Para funcionalidad completa:

  • Acceso de lectura a computadoras, políticas, scripts
  • Acceso de actualización para actualizaciones de inventario
  • Acceso de ejecución para políticas y scripts

Para modo de solo lectura:

  • Acceso de lectura solo a computadoras

Solución de Problemas

Problemas de Autenticación

  • Verifica tus credenciales de API
  • Asegúrate de que el usuario de API tenga los permisos requeridos
  • Verifica la conectividad de red con Jamf Pro

Fallos de Ejecución de Herramientas

  • Verifica que los IDs de dispositivos sean correctos
  • Asegúrate de que las políticas/scripts existan en Jamf Pro
  • Verifica que los dispositivos estén en línea y gestionados

Rendimiento

  • Las solicitudes de inventario grandes pueden tomar tiempo
  • Usa filtros de búsqueda para limitar resultados
  • Considera implementar paginación para conjuntos de datos grandes

Perfiles de Configuración

  • La API Clásica devuelve perfiles de configuración de computadoras bajo os_x_configuration_profiles (con guiones bajos)
  • Los perfiles de dispositivos móviles se devuelven bajo configuration_profiles
  • Los detalles del perfil usan os_x_configuration_profile (singular) para computadoras
  • Los clientes de API manejan estas variaciones de nombres de campo automáticamente

Consideraciones de Seguridad

  • Almacena las credenciales de forma segura (usa variables de entorno)
  • Usa el modo de solo lectura cuando no se necesite acceso de escritura
  • Rota regularmente las credenciales de API
  • Monitorea el uso de la API para detectar anomalías
  • Implementa listas de permitidos de IP en Jamf Pro si es posible

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Agrega pruebas para la nueva funcionalidad
  4. Envía una solicitud de extracción (pull request)

Licencia

MIT