Jamf Pro MCP Server

Um servidor para gerenciar dispositivos Apple através da API do Jamf Pro.

Documentação

Servidor MCP Jamf Pro

Um servidor MCP (Model Context Protocol) abrangente que permite que assistentes de IA interajam com o Jamf Pro para gerenciamento completo de dispositivos Apple, incluindo computadores, dispositivos móveis, políticas, scripts, perfis de configuração, pacotes e relatórios.

🚀 Início 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

Configure suas credenciais no Claude Desktop (veja a seção Configuração abaixo).

Recursos

Ferramentas (Funções Executáveis)

Gerenciamento de Dispositivos

searchDevices: Encontre dispositivos por nome, número de série, endereço IP ou nome de usuário (suporta correspondência parcial)
getDeviceDetails: Recupere informações abrangentes do dispositivo por ID ou nome
checkDeviceCompliance: Encontre dispositivos que não reportaram em X dias (otimizado para grandes frotas)
getDevicesBatch: Obtenha detalhes de vários dispositivos de forma eficiente
updateInventory: Force a atualização do inventário nos dispositivos

Gerenciamento de Políticas

listPolicies: Liste todas as políticas no Jamf Pro
getPolicyDetails: Obtenha informações detalhadas sobre uma política específica por ID ou nome (inclui escopo, scripts com conteúdo completo e pacotes — você pode ver exatamente quais scripts e pacotes estão anexados a qualquer política)
searchPolicies: Pesquise políticas por nome ou ID (suporta correspondência parcial)
executePolicy: Execute políticas em dispositivos específicos (política e dispositivo podem ser especificados por ID ou nome, requer confirmação)

Gerenciamento de Scripts

deployScript: Execute scripts para solução de problemas (com confirmação)
getScriptDetails: Obtenha o conteúdo completo do script e metadados, incluindo parâmetros, notas e requisitos de sistema operacional

Gerenciamento de Perfis de Configuração

listConfigurationProfiles: Liste todos os perfis de configuração (computador ou dispositivo móvel)
getConfigurationProfileDetails: Obtenha informações detalhadas sobre um perfil de configuração específico
searchConfigurationProfiles: Pesquise perfis de configuração por nome
deployConfigurationProfile: Implante um perfil de configuração em um ou mais dispositivos (com confirmação)
removeConfigurationProfile: Remova um perfil de configuração de um ou mais dispositivos (com confirmação)

Gerenciamento de Pacotes

listPackages: Liste todos os pacotes com nome, versão, categoria e tamanho
getPackageDetails: Obtenha informações detalhadas do pacote, incluindo metadados, requisitos e notas
searchPackages: Pesquise pacotes por nome, nome de arquivo ou categoria
getPackageDeploymentHistory: Obtenha histórico de implantação e estatísticas de um pacote
getPoliciesUsingPackage: Encontre todas as políticas que usam um pacote específico

Gerenciamento de Grupos de Computadores

listComputerGroups: Liste grupos de computadores (grupos inteligentes, grupos estáticos ou todos)
getComputerGroupDetails: Obtenha informações detalhadas sobre um grupo específico, incluindo associação e critérios de grupo inteligente
searchComputerGroups: Pesquise grupos de computadores por nome
getComputerGroupMembers: Obtenha todos os membros de um grupo de computadores específico
createStaticComputerGroup: Crie um novo grupo de computadores estático com membros especificados (com confirmação)
updateStaticComputerGroup: Atualize a associação de um grupo de computadores estático (com confirmação)
deleteComputerGroup: Exclua um grupo de computadores (com confirmação)

Gerenciamento de Dispositivos Móveis

searchMobileDevices: Pesquise dispositivos móveis por nome, número de série, UDID ou outros critérios
getMobileDeviceDetails: Obtenha informações detalhadas sobre um dispositivo móvel específico, incluindo hardware, sistema operacional, bateria e status de gerenciamento
listMobileDevices: Liste todos os dispositivos móveis no Jamf Pro com informações básicas
updateMobileDeviceInventory: Force uma atualização de inventário em um dispositivo móvel específico
sendMDMCommand: Envie comandos MDM para dispositivos móveis (bloquear, apagar, limpar senha, etc.) com confirmação para ações destrutivas
listMobileDeviceGroups: Liste grupos de dispositivos móveis (grupos inteligentes, grupos estáticos ou todos)
getMobileDeviceGroupDetails: Obtenha informações detalhadas sobre um grupo de dispositivos móveis específico, incluindo associação e critérios

Recursos (Dados Somente Leitura)

jamf://inventory/computers: Lista paginada de dispositivos
jamf://inventory/mobile-devices: Lista paginada de dispositivos móveis
jamf://reports/compliance: Relatório de conformidade de segurança e patches
jamf://reports/mobile-device-compliance: Relatório de conformidade de dispositivos móveis mostrando status de gerenciamento e problemas
jamf://reports/storage: Análise de uso de disco
jamf://reports/os-versions: Distribuição de versões do sistema operacional

Prompts (Modelos de Fluxo de Trabalho)

troubleshoot-device: Solução de problemas de dispositivo passo a passo
deploy-software: Fluxo de trabalho de implantação de software
compliance-check: Relatório abrangente de conformidade
mass-update: Operações em lote de dispositivos
storage-cleanup: Gerenciamento de espaço em disco

Instalação

Clone este repositório
Instale as dependências:
```
cd jamf-mcp-server
npm install
```
Compile o projeto:
```
npm run build
```

Configuração

Configurando a Autenticação da API do Jamf Pro

No Jamf Pro, vá para Configurações > Sistema > Funções e Clientes de API
Crie uma nova Função de API com as permissões necessárias
Crie um novo Cliente de API:
- Atribua a Função de API que você criou
- Anote o ID do Cliente e gere um Segredo do Cliente
Use essas credenciais nas suas variáveis de ambiente

Configuração do Claude Desktop

Adicione ao seu arquivo de configuração do 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"
      }
    }
  }
}

Exemplos de Uso

Nota: A maioria das ferramentas suporta pesquisa por ID e nome. Ao pesquisar por nome, correspondências parciais são suportadas. Por exemplo, você pode pesquisar por "Chrome" para encontrar todos os itens que contenham essa palavra no nome.

Pesquisar um Dispositivo

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

Verificar Detalhes do Dispositivo

Show me the details for device ID 123

Verificar Conformidade do Dispositivo (NOVO - Otimizado)

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

Isso usará a nova ferramenta checkDeviceCompliance que processa eficientemente todos os dispositivos e fornece:

Estatísticas resumidas (conforme/não conforme/desconhecido)
Dispositivos críticos (90+ dias)
Dispositivos de aviso (30-90 dias)
Lista detalhada opcional de dispositivos

Análise de Políticas - Ver Scripts e Pacotes

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

Gerenciamento de Perfis de Configuração

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

Operações em Lote de Dispositivos (NOVO)

Get details for devices 123, 456, and 789

Implantar Software

Install Slack on all marketing team Macs

Análise de Armazenamento

Which devices have less than 10GB free space?

Operações de Políticas (NOVO)

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

Operações de Scripts (NOVO)

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

Gerenciamento de Pacotes (NOVO)

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

Gerenciamento de Grupos de Computadores (NOVO)

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

Gerenciamento de Dispositivos Móveis (NOVO)

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 Suportados

Os seguintes comandos MDM são suportados para dispositivos móveis:

DeviceLock: Bloqueie o dispositivo imediatamente
EraseDevice: Apague o dispositivo (requer confirmação)
ClearPasscode: Remova a senha do dispositivo (requer confirmação)
RestartDevice: Reinicie o dispositivo
ShutDownDevice: Desligue o dispositivo
EnableLostMode: Ative o Modo Perdido
DisableLostMode: Desative o Modo Perdido
PlayLostModeSound: Toque um som no dispositivo perdido
UpdateInventory: Force a atualização do inventário
ClearRestrictionsPassword: Limpe a senha de restrições (requer confirmação)
Comandos de Configurações: Ativar/desativar Bluetooth, WiFi, Roaming de Dados, Roaming de Voz, Hotspot Pessoal

Recursos de Segurança

Modo Somente Leitura: Defina JAMF_READ_ONLY=true para evitar qualquer modificação
Confirmação Necessária: Operações destrutivas exigem confirmação explícita
Tratamento de Erros: Mensagens de erro abrangentes e recuperação
Limitação de Taxa: Respeita os limites da API do Jamf Pro
Trilha de Auditoria: Todas as operações são registradas

Tratamento de Erros Aprimorado (v1.1.0)

O servidor agora inclui tratamento abrangente de erros e lógica de nova tentativa:

Recursos

Nova Tentativa Automática: Backoff exponencial para falhas transitórias
Disjuntor: Previne falhas em cascata
Mensagens de Erro Aprimoradas: Informações detalhadas de erro com sugestões acionáveis
Registro de Solicitações/Respostas: Modo de depuração para solução de problemas
Limitação de Taxa: Limitador de taxa integrado para prevenir limitação da API

Configuração

Adicione estas variáveis de ambiente opcionais à sua configuração do 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 Erro

O modo aprimorado fornece tipos de erro específicos com sugestões úteis:

JamfAPIError: Erros gerais de API com códigos de status e sugestões
NetworkError: Problemas de conexão com dicas de solução de problemas de rede
AuthenticationError: Falhas de autenticação com etapas de verificação de credenciais
RateLimitError: Erros de limite de taxa com tempo de nova tentativa
ValidationError: Erros de validação de entrada com feedback específico por campo

Consulte docs/ERROR_HANDLING.md para documentação detalhada.

Desenvolvimento

Configuração de Desenvolvimento Local

Para desenvolvimento local sem o Claude Desktop, crie um arquivo .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

Executando em Modo de Desenvolvimento

npm run dev

Testando com o MCP Inspector

npm run inspector

Executando Testes

npm test

Requisitos da API

Este servidor requer:

Jamf Pro versão 10.35.0 ou posterior
Usuário de API com permissões apropriadas
Acesso de rede à sua instância do Jamf Pro

Permissões de API Recomendadas

Para funcionalidade completa:

Acesso de leitura para computadores, políticas, scripts
Acesso de atualização para atualizações de inventário
Acesso de execução para políticas e scripts

Para modo somente leitura:

Acesso de leitura apenas para computadores

Solução de Problemas

Problemas de Autenticação

Verifique suas credenciais de API
Garanta que o usuário de API tenha as permissões necessárias
Verifique a conectividade de rede com o Jamf Pro

Falhas na Execução de Ferramentas

Verifique se os IDs dos dispositivos estão corretos
Garanta que políticas/scripts existam no Jamf Pro
Verifique se os dispositivos estão online e gerenciados

Desempenho

Solicitações de inventário grandes podem levar tempo
Use filtros de pesquisa para limitar resultados
Considere implementar paginação para grandes conjuntos de dados

Perfis de Configuração

A API Clássica retorna perfis de configuração de computador sob os_x_configuration_profiles (com sublinhados)
Perfis de dispositivos móveis são retornados sob configuration_profiles
Detalhes do perfil usam os_x_configuration_profile (singular) para computadores
Os clientes de API lidam com essas variações de nomes de campos automaticamente

Considerações de Segurança

Armazene credenciais com segurança (use variáveis de ambiente)
Use modo somente leitura quando acesso de escrita não for necessário
Rotacione regularmente as credenciais de API
Monitore o uso da API para anomalias
Implemente lista de permissões de IP no Jamf Pro, se possível

Contribuindo

Contribuições são bem-vindas! Por favor:

Faça um fork do repositório
Crie um branch de recurso
Adicione testes para novas funcionalidades
Envie um pull request

Licença

MIT