xcsimctl

Gerenciar simuladores do Xcode.

GitHub
1
Experimente este MCPPatrocinado

Documentação

Servidor MCP SimCtl

Um servidor Model Context Protocol (MCP) que fornece acesso estruturado ao gerenciamento do Simulador iOS por meio de comandos xcrun simctl.

Instalação

Método 1: Usando uvx

  1. Pré-requisitos:

    • Python 3.13+
    • Xcode com Command Line Tools instalado
    • uvx: curl -LsSf https://astral.sh/uv/install.sh | sh

  2. Execute diretamente com uvx:

    uvx simctl-mcp-server

Método 2: Instalação para Desenvolvimento Local

  1. Pré-requisitos:

    • Python 3.13+
    • Xcode com Command Line Tools instalado

  2. Clone e instale:

    git clone https://github.com/nzrsky/simctl-mcp-server
cd simctl-mcp-server
pip install .

  3. Execute o servidor:

    simctl-mcp-server

Método 3: Compilar a partir do Código Fonte

  1. Compile o wheel: 
    python -m build --wheel
pip install dist/simctl_mcp_server-0.1.0-py3-none-any.whl

Configuração

Para Claude Desktop

Adicione ao seu ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "simctl": {
      "command": "simctl-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Ou se estiver usando uvx:

{
  "mcpServers": {
    "simctl": {
      "command": "uvx",
      "args": ["simctl-mcp-server"],
      "env": {}
    }
  }
}

Para VS Code com Extensão MCP

  1. Instale a Extensão MCP no marketplace do VS Code
  2. Adicione a configuração do servidor às configurações do VS Code (settings.json):
{
  "mcp.servers": {
    "simctl": {
      "command": "simctl-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Ou se estiver usando uvx:

{
  "mcp.servers": {
    "simctl": {
      "command": "uvx",
      "args": ["simctl-mcp-server"],
      "env": {}
    }
  }
}
  1. Reinicie o VS Code para carregar o servidor MCP
  2. Use a Paleta de Comandos (Cmd+Shift+P) e pesquise por comandos "MCP" para interagir com as ferramentas do simulador

Para Outros Clientes MCP

O servidor executa em stdio, então você pode invocá-lo diretamente:

Com o pacote instalado:

simctl-mcp-server

Com uvx:

uvx simctl-mcp-server

Ferramentas Disponíveis

Gerenciamento de Dispositivos

  • simctl_list_devices - Lista todos os simuladores e seus estados
  • simctl_boot_device - Inicializa um simulador
  • simctl_shutdown_device - Desliga um simulador
  • simctl_create_device - Cria um novo simulador
  • simctl_delete_device - Exclui simuladores

Gerenciamento de Aplicativos

  • simctl_install_app - Instala um aplicativo (pacote .app ou .ipa)
  • simctl_launch_app - Inicia um aplicativo com opções
  • simctl_terminate_app - Encerra um aplicativo em execução

Mídia e Capturas de Tela

  • simctl_screenshot - Tira capturas de tela
  • simctl_record_video - Grava vídeo (inicia a gravação)

Testes e Desenvolvimento

  • simctl_push_notification - Envia notificações push
  • simctl_privacy_control - Gerencia permissões de aplicativos
  • simctl_set_location - Define localização/GPS do dispositivo
  • simctl_status_bar_override - Substitui a aparência da barra de status
  • simctl_ui_appearance - Controla o modo claro/escuro

Exemplos de Uso

Operações Básicas de Dispositivo

# List all devices
"List all available iOS simulators"

# Boot a specific device
"Boot the iPhone 15 Pro simulator"

# Create a new simulator
"Create a new iPhone 14 simulator named 'Test Device' with iOS 17.0"

Testes de Aplicativos

# Install and launch an app
"Install MyApp.app on the booted simulator and launch it"

# Take a screenshot
"Take a screenshot of the current simulator and save it to ~/Desktop/screenshot.png"

# Send a push notification
"Send a push notification with title 'Hello' and body 'Test message' to com.example.myapp"

Configuração de Testes de UI

# Set up a controlled testing environment
"Set the simulator to dark mode, override the status bar to show full battery and strong WiFi, and set the time to 9:41 AM"

# Grant permissions for testing
"Grant photo library access to com.example.myapp on the booted simulator"

Testes de Localização

# Set specific location
"Set the simulator location to Apple Park (37.334606, -122.009102)"

# Clear location
"Clear the simulated location on the booted device"

Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

  • Falhas de comando: Retorna mensagens de erro detalhadas do simctl
  • Xcode ausente: Detecta quando xcrun simctl não está disponível
  • Parâmetros inválidos: Valida os parâmetros de entrada antes da execução
  • Operações de arquivo: Gerencia arquivos temporários para notificações push com segurança

Considerações de Segurança

  • O servidor expõe apenas operações de leitura e gerenciamento do simulador
  • Sem acesso ao sistema de arquivos do host além dos caminhos de aplicativos especificados
  • Os payloads de notificações push são validados quanto à estrutura
  • As alterações de permissões de privacidade são explícitas e registradas

Notas de Desenvolvimento

  • Construído especificamente para fluxos de trabalho de desenvolvimento iOS
  • Otimizado para tarefas comuns de gerenciamento de simuladores
  • Análise de saída estruturada para respostas JSON
  • Suporte para operações individuais e em lote
  • Compatível com recursos do simulador do Xcode 15+