iOS Simulator MCP Server

iOS Simulator MCP Server

Um servidor Model Context Protocol (MCP) para interagir com simuladores iOS. Este servidor permite que você interaja com simuladores iOS obtendo informações sobre eles, controlando interações de UI e inspecionando elementos de UI.

Aviso de Segurança: Vulnerabilidades de injeção de comandos presentes em versões < 1.3.3 foram corrigidas. Atualize para v1.3.3 ou posterior. Consulte SECURITY.md para detalhes.

https://github.com/user-attachments/assets/a88e449c-8f1d-46a5-9816-0f97e071c460

🌟 Destaques

Este projeto foi apresentado e mencionado em várias publicações e recursos:

• Artigo sobre Melhores Práticas do Claude Code - Blog de engenharia da Anthropic mostrando melhores práticas
• React Native Newsletter Edição 187 - Apresentado no boletim informativo mais popular da comunidade React Native
• Mobile Automation Newsletter - #56 - Apresentado em um boletim informativo de longa duração sobre recursos de teste e automação móvel
• Lista punkeye/awesome-mcp-server - Listado em uma das coleções curadas mais populares de servidores MCP

Ferramentas

get_booted_sim_id

Descrição: Obter o ID do simulador iOS atualmente inicializado

Parâmetros: Sem parâmetros

open_simulator

Descrição: Abre o aplicativo Simulador iOS

Parâmetros: Sem parâmetros

ui_describe_all

Descrição: Descreve informações de acessibilidade para toda a tela no Simulador iOS

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

ui_tap

Descrição: Toque na tela do Simulador iOS

Parâmetros:

{
  /**
   * Press duration in seconds (decimal numbers allowed)
   */
  duration?: string;
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The x-coordinate */
  x: number;
  /** The y-coordinate */
  y: number;
}

ui_type

Descrição: Insere texto no Simulador iOS

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /**
   * Text to input
   * Format: ASCII printable characters only
   */
  text: string;
}

ui_swipe

Descrição: Deslize na tela do Simulador iOS

Parâmetros:

{
  /**
   * Swipe duration in seconds (decimal numbers allowed)
   */
  duration?: string;
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The starting x-coordinate */
  x_start: number;
  /** The starting y-coordinate */
  y_start: number;
  /** The ending x-coordinate */
  x_end: number;
  /** The ending y-coordinate */
  y_end: number;
  /** The size of each step in the swipe (default is 1) */
  delta?: number;
}

ui_describe_point

Descrição: Retorna o elemento de acessibilidade nas coordenadas fornecidas na tela do Simulador iOS

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The x-coordinate */
  x: number;
  /** The y-coordinate */
  y: number;
}

ui_find_element

Descrição: Pesquisa a árvore de acessibilidade e retorna elementos que correspondem aos critérios fornecidos

Parâmetros:

{
  /** Array of search strings. An element matches if ANY string matches against its AXLabel or AXUniqueId */
  search: string[];
  /** Filter by element type (e.g. 'Button', 'StaticText', 'Group'). Case-insensitive exact match */
  type?: string;
  /** Match mode: 'substring' (default) or 'exact' */
  matchMode?: "substring" | "exact";
  /** Whether search matching is case-sensitive (default: false) */
  caseSensitive?: boolean;
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

ui_view

Descrição: Obter o conteúdo de imagem de uma captura de tela compactada da visualização atual do simulador

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

screenshot

Descrição: Tira uma captura de tela do Simulador iOS

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** File path where the screenshot will be saved. If relative, it uses the directory specified by the `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` env var, or `~/Downloads` if not set. */
  output_path: string;
  /** Image format (png, tiff, bmp, gif, or jpeg). Default is png. */
  type?: "png" | "tiff" | "bmp" | "gif" | "jpeg";
  /** Display to capture (internal or external). Default depends on device type. */
  display?: "internal" | "external";
  /** For non-rectangular displays, handle the mask by policy (ignored, alpha, or black) */
  mask?: "ignored" | "alpha" | "black";
}

record_video

Descrição: Grava um vídeo do Simulador iOS usando simctl diretamente

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Optional output path. If not provided, a default name will be used. The file will be saved in the directory specified by `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` or in `~/Downloads` if the environment variable is not set. */
  output_path?: string;
  /** Specifies the codec type: "h264" or "hevc". Default is "hevc". */
  codec?: "h264" | "hevc";
  /** Display to capture: "internal" or "external". Default depends on device type. */
  display?: "internal" | "external";
  /** For non-rectangular displays, handle the mask by policy: "ignored", "alpha", or "black". */
  mask?: "ignored" | "alpha" | "black";
  /** Force the output file to be written to, even if the file already exists. */
  force?: boolean;
}

stop_recording

Descrição: Para a gravação de vídeo do simulador usando killall

Parâmetros: Sem parâmetros

install_app

Descrição: Instala um pacote de aplicativo (.app ou .ipa) no Simulador iOS

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Path to the app bundle (.app directory or .ipa file) to install */
  app_path: string;
}

launch_app

Descrição: Inicia um aplicativo no Simulador iOS pelo identificador do pacote

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Bundle identifier of the app to launch (e.g., com.apple.mobilesafari) */
  bundle_id: string;
  /** Terminate the app if it is already running before launching */
  terminate_running?: boolean;
  /** Optional environment variables passed via SIMCTL_CHILD_ to simctl launch */
  env?: Record<string, string>;
}

Notas: As variáveis de ambiente são passadas usando SIMCTL_CHILD_ porque simctl launch não suporta --env/--envs em todas as versões do Xcode.

Exemplo:

{
  "bundle_id": "com.example.app",
  "terminate_running": true,
  "env": {
    "FOO": "bar",
    "BAZ": "qux"
  }
}

terminate_app

Descrição: Encerra um aplicativo em execução no Simulador iOS pelo identificador do pacote. Útil para testar fluxos de inicialização a frio e verificar a recuperação de falhas sem reinstalar o aplicativo.

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Bundle identifier of the app to terminate (e.g., com.apple.mobilesafari) */
  bundle_id: string;
}

open_url

Descrição: Abre uma URL ou deep link no Simulador iOS. Lida com URLs https:// (via Safari), esquemas de URL personalizados e links universais — essencial para testar roteamento de deep link e fluxos de redirecionamento OAuth.

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The URL or deep link to open (e.g., https://example.com or myapp://screen/detail) */
  url: string;
}

list_apps

Descrição: Lista todos os aplicativos instalados no Simulador iOS com seus identificadores de pacote e nomes de exibição, ordenados alfabeticamente. Elimina a necessidade de procurar IDs de pacote manualmente antes de chamar launch_app ou terminate_app.

Parâmetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

💡 Caso de Uso: Etapa de QA via Chamadas de Ferramentas MCP

Este servidor MCP permite que assistentes de IA integrados a um cliente Model Context Protocol (MCP) executem tarefas de Garantia de Qualidade fazendo chamadas de ferramentas. Isso é útil imediatamente após a implementação de recursos para ajudar a garantir a consistência da UI e o comportamento correto.

Como Usar

Após a implementação de um recurso, instrua seu assistente de IA no ambiente do cliente MCP a usar as ferramentas disponíveis. Por exemplo, no modo agente do Cursor, você pode usar os prompts abaixo para validar e documentar rapidamente as interações de UI.

Exemplos de Prompts

• Verificar Elementos de UI:

  Verify all accessibility elements on the current screen
  

• Confirmar Entrada de Texto:

  Enter "QA Test" into the text input field and confirm the input is correct
  

• Verificar Resposta ao Toque:

  Tap on coordinates x=250, y=400 and verify the expected element is triggered
  

• Validar Ação de Deslize:

  Swipe from x=150, y=600 to x=150, y=100 and confirm correct behavior
  

• Verificação Detalhada de Elemento:

  Describe the UI element at position x=300, y=350 to ensure proper labeling and functionality
  

• Mostrar a Tela do Simulador ao Seu Agente de IA:

  View the current simulator screen
  

• Tirar Captura de Tela:

  Take a screenshot of the current simulator screen and save it to my_screenshot.png
  

• Gravar Vídeo:

  Start recording a video of the simulator screen (saves to the default output directory, which is `~/Downloads` unless overridden by `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR`)
  

• Parar Gravação:

  Stop the current simulator screen recording
  

• Instalar Aplicativo:

  Install the app at path/to/MyApp.app on the simulator
  

• Iniciar Aplicativo:

  Launch the Safari app (com.apple.mobilesafari) on the simulator
  

🧭 Dica: Deep Link Direto para uma Tela

Os agentes podem desperdiçar muitas iterações tocando e deslizando até uma rota profundamente aninhada. Quando seu aplicativo registra um esquema de URL (ou Link Universal), geralmente é mais rápido pular diretamente para a tela de destino em vez de navegar passo a passo.

Você pode abrir um deep link com uri-scheme:

npx uri-scheme open "myapp://products/42" --ios

Isso tem como alvo o simulador atualmente inicializado. Por baixo dos panos, é equivalente a:

xcrun simctl openurl booted "myapp://products/42"

Ambos funcionam para esquemas personalizados (myapp://...) e URLs da web (https://..., que acionam Links Universais se seu aplicativo estiver configurado para eles).

Exemplo de prompt:

Open the deep link myapp://products/42 in the simulator, then verify the product
details screen is shown

Use isso para encurtar os loops do agente: faça deep link para a tela em teste e, em seguida, use as ferramentas de UI (ui_describe_all, ui_tap, ui_view, …) para validá-la.

Pré-requisitos

• Node.js 20 ou posterior
• macOS (pois os simuladores iOS estão disponíveis apenas no macOS)
• Xcode e simuladores iOS instalados
• Ferramenta IDB do Facebook (veja o guia de instalação)

Instalação

Esta seção fornece instruções para integrar o servidor MCP do Simulador iOS com diferentes clientes Model Context Protocol (MCP).

Instalação com Cursor

O Cursor gerencia servidores MCP por meio de seu arquivo de configuração localizado em ~/.cursor/mcp.json.

Opção 1: Usando NPX (Recomendado)

1. Edite o arquivo de configuração MCP do Cursor. Você pode abri-lo diretamente no Cursor ou usar um comando como:

   # Open with your default editor (or use 'code', 'vim', etc.)
   open ~/.cursor/mcp.json
   # Or use Cursor's command if available
   # cursor ~/.cursor/mcp.json
   

2. Adicione ou atualize a seção mcpServers com a configuração do servidor do simulador iOS:

   {
     "mcpServers": {
       // ... other servers might be listed here ...
       "ios-simulator": {
         "command": "npx",
         "args": ["-y", "ios-simulator-mcp"]
       }
     }
   }
   

   Certifique-se de que a estrutura JSON seja válida, especialmente se mcpServers já existir.

   Se preferir pnpm, use o executor dlx em vez disso:

   {
     "mcpServers": {
       "ios-simulator": {
         "command": "pnpm",
         "args": ["dlx", "ios-simulator-mcp"]
       }
     }
   }
   

3. Reinicie o Cursor para que as alterações tenham efeito.

Opção 2: Desenvolvimento Local

1. Clone este repositório:

   git clone https://github.com/joshuayoes/ios-simulator-mcp
   cd ios-simulator-mcp
   

2. Instale as dependências (npm é o padrão; pnpm também é suportado):

   npm install
   # or, using pnpm (installs from the committed pnpm-lock.yaml):
   pnpm install
   

3. Compile o projeto:

   npm run build
   # or:
   pnpm run build
   

4. Edite o arquivo de configuração MCP do Cursor (como mostrado na Opção 1).
5. Adicione ou atualize a seção mcpServers, apontando para sua compilação local:

   {
     "mcpServers": {
       // ... other servers might be listed here ...
       "ios-simulator": {
         "command": "node",
         "args": ["/full/path/to/your/ios-simulator-mcp/build/index.js"]
       }
     }
   }
   

   Importante: Substitua /full/path/to/your/ pelo caminho absoluto para onde você clonou o repositório ios-simulator-mcp.
6. Reinicie o Cursor para que as alterações tenham efeito.

Instalação com Claude Code

O CLI do Claude Code pode gerenciar servidores MCP usando os comandos claude mcp ou editando seus arquivos de configuração diretamente. Para mais detalhes sobre a configuração MCP do Claude Code, consulte a documentação oficial.

Opção 1: Usando NPX (Recomendado)

1. Adicione o servidor usando o comando claude mcp add:

   claude mcp add ios-simulator npx ios-simulator-mcp
   # or, with pnpm:
   claude mcp add ios-simulator -- pnpm dlx ios-simulator-mcp
   

2. Reinicie quaisquer sessões do Claude Code em execução, se necessário.

Opção 2: Desenvolvimento Local

1. Clone este repositório, instale as dependências e compile o projeto conforme descrito nas etapas 1-3 do "Desenvolvimento Local" do Cursor.
2. Adicione o servidor usando o comando claude mcp add, apontando para sua compilação local:

   claude mcp add ios-simulator -- node "/full/path/to/your/ios-simulator-mcp/build/index.js"
   

   Importante: Substitua /full/path/to/your/ pelo caminho absoluto para onde você clonou o repositório ios-simulator-mcp.
3. Reinicie quaisquer sessões do Claude Code em execução, se necessário.

Configuração

Variáveis de Ambiente

Variável	Descrição	Exemplo
IOS_SIMULATOR_MCP_FILTERED_TOOLS	Uma lista separada por vírgulas de nomes de ferramentas para filtrar do registro.	screenshot,record_video,stop_recording
IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR	Especifica um diretório padrão para arquivos de saída, como capturas de tela e gravações de vídeo. Se não for definido, ~/Downloads será usado. Isso pode ser útil se seu agente tiver acesso limitado ao sistema de arquivos.	~/Code/awesome-project/tmp
IOS_SIMULATOR_MCP_IDB_PATH	Especifica um caminho personalizado para o executável IDB. Se não for definido, idb será usado (assumindo que esteja no seu PATH). Útil se o IDB estiver instalado em um local não padrão.	~/bin/idb ou /usr/local/bin/idb

Exemplo de Configuração

{
  "mcpServers": {
    "ios-simulator": {
      "command": "npx",
      "args": ["-y", "ios-simulator-mcp"],
      "env": {
        "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "screenshot,record_video,stop_recording",
        "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "~/Code/awesome-project/tmp",
        "IOS_SIMULATOR_MCP_IDB_PATH": "~/bin/idb"
      }
    }
  }
}

Listagens de Servidores no Registro MCP

Licença

MIT