iOS Simulator MCP Server

iOS simülatörleriyle etkileşim kurmak için bir Model Context Protocol (MCP) sunucusu. Bu sunucu, iOS simülatörleri hakkında bilgi alarak, UI etkileşimlerini kontrol ederek ve UI öğelerini inceleyerek simülatörlerle etkileşim kurmanızı sağlar.

Güvenlik Uyarısı: 1.3.3'ten önceki sürümlerdeki komut enjeksiyonu açıkları giderilmiştir. Lütfen v1.3.3 veya daha yeni sürüme güncelleyin. Ayrıntılar için SECURITY.md dosyasına bakın.

https://github.com/user-attachments/assets/453ebe7b-cc93-4ac2-b08d-0f8ac8339ad3

🌟 Öne Çıkan Yayınlar

Bu proje çeşitli yayınlarda ve kaynaklarda öne çıkarılmış ve bahsedilmiştir:

• Claude Code Best Practices makalesi - Anthropic'in mühendislik bloğundaki en iyi uygulamalar
• React Native Newsletter Issue 187 - En popüler React Native topluluk haber bülteninde öne çıkarılmış
• Mobile Automation Newsletter - #56 - Mobil test ve otomasyon kaynakları hakkında uzun süredir yayınlanan bir haber bülteninde öne çıkarılmış
• punkeye/awesome-mcp-server listesi - En popüler curated awesome MCP sunucuları koleksiyonlarından birinde listelenmektedir

Araçlar

get_booted_sim_id

Açıklama: Şu anda açılı iOS simülatörünün ID'sini alır

Parametreler: Parametre Yok

open_simulator

Açıklama: iOS Simulator uygulamasını açar

Parametreler: Parametre Yok

ui_describe_all

Açıklama: iOS Simulator'da tüm ekran için erişilebilirlik bilgilerini açıklar

Parametreler:

{
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
}

ui_tap

Açıklama: iOS Simulator'da ekrana dokunur

Parametreler:

{
  /**
   * Basılı tutma süresi saniye cinsinden (ondalık sayılara izin verilir)
   */
  duration?: string;
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
  /** x-koordinatı */
  x: number;
  /** y-koordinatı */
  y: number;
}

ui_type

Açıklama: iOS Simulator'a metin girer

Parametreler:

{
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
  /**
   * Girilecek metin
   * Format: Yalnızca ASCII yazdırılabilir karakterler
   */
  text: string;
}

ui_swipe

Açıklama: iOS Simulator'da ekran üzerinde kaydırma hareketi yapar

Parametreler:

{
  /**
   * Kaydırma süresi saniye cinsinden (ondalık sayılara izin verilir)
   */
  duration?: string;
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
  /** Başlangıç x-koordinatı */
  x_start: number;
  /** Başlangıç y-koordinatı */
  y_start: number;
  /** Bitiş x-koordinatı */
  x_end: number;
  /** Bitiş y-koordinatı */
  y_end: number;
  /** Kaydırma işleminin her adımının boyutu (varsayılan 1) */
  delta?: number;
}

ui_describe_point

Açıklama: iOS Simulator'un ekranında verilen koordinatlardaki erişilebilirlik öğesini döndürür

Parametreler:

{
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
  /** x-koordinatı */
  x: number;
  /** y-koordinatı */
  y: number;
}

ui_find_element

Açıklama: Erişilebilirlik ağacında arama yapar ve verilen kriterlere uygun öğeleri döndürür

Parametreler:

{
  /** Arama dizeleri dizisi. Herhangi bir dize AXLabel veya AXUniqueId ile eşleşirse öğe eşleşir */
  search: string[];
  /** Öğe türüne göre filtrele (ör. 'Button', 'StaticText', 'Group'). Büyük/küçük harfe duyarsız tam eşleşme */
  type?: string;
  /** Eşleştirme modu: 'substring' (varsayılan) veya 'exact' */
  matchMode?: "substring" | "exact";
  /** Arama eşleştirmesinin büyük/küçük harfe duyarlı olup olmadığı (varsayılan: false) */
  caseSensitive?: boolean;
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
}

ui_view

Açıklama: Geçerli simülatör görünümünün sıkıştırılmış ekran görüntüsünün görüntü içeriğini alır

Parametreler:

{
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
}

screenshot

Açıklama: iOS Simulator'un ekran görüntüsünü alır

Parametreler:

{
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
  /** Ekran görüntüsünün kaydedileceği dosya yolu. Göreli ise, `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` env var ile belirtilen dizini veya ayarlanmamışsa `~/Downloads` dizinini kullanır. */
  output_path: string;
  /** Resim formatı (png, tiff, bmp, gif veya jpeg). Varsayılan png'dir. */
  type?: "png" | "tiff" | "bmp" | "gif" | "jpeg";
  /** Yakalanacak ekran (internal veya external). Varsayılan cihaz türüne bağlı. */
  display?: "internal" | "external";
  /** Dikdörtgen olmayan ekranlar için, maskeyi ilkesi uyarında işle (ignored, alpha veya black) */
  mask?: "ignored" | "alpha" | "black";
}

record_video

Açıklama: simctl'i doğrudan kullanarak iOS Simulator'ın bir video kaydını alır

Parametreler:

{
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
  /** İsteğe bağlı çıkış yolu. Sağlanmamışsa, varsayılan bir ad kullanılacaktır. Dosya `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` tarafından belirtilen dizine veya ortam değişkeni ayarlanmamışsa `~/Downloads` dizinine kaydedilecektir. */
  output_path?: string;
  /** Codec türünü belirtir: "h264" veya "hevc". Varsayılan "hevc"dir. */
  codec?: "h264" | "hevc";
  /** Yakalanacak ekran: "internal" veya "external". Varsayılan cihaz türüne bağlı. */
  display?: "internal" | "external";
  /** Dikdörtgen olmayan ekranlar için, maskeyi ilkesi uyarında işle: "ignored", "alpha" veya "black". */
  mask?: "ignored" | "alpha" | "black";
  /** Dosya zaten varsa bile çıkış dosyasının yazılmaya zorlanması. */
  force?: boolean;
}

stop_recording

Açıklama: killall kullanarak simülatör video kaydını durdurur

Parametreler: Parametre Yok

install_app

Açıklama: iOS Simulator'a bir uygulama paketi (.app veya .ipa) yükler

Parametreler:

{
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
  /** Yüklenecek uygulama paketinin yolu (.app dizini veya .ipa dosyası) */
  app_path: string;
}

launch_app

Açıklama: Bundle tanımlayıcısı kullanarak iOS Simulator'da bir uygulamayı başlatır

Parametreler:

{
  /**
   * Hedefin Udid'i, ayrıca IDB_UDID env var ile de ayarlanabilir
   * Format: UUID (8-4-4-4-12 onaltılı karakter)
   */
  udid?: string;
  /** Başlatılacak uygulamanın bundle tanımlayıcısı (ör. com.apple.mobilesafari) */
  bundle_id: string;
  /** Uygulama zaten çalışıyorsa, başlatmadan önce onu sonlandır */
  terminate_running?: boolean;
  /** simctl launch'a SIMCTL_CHILD_ aracılığıyla geçirilen isteğe bağlı ortam değişkenleri */
  env?: Record<string, string>;
}

Notlar: Ortam değişkenleri SIMCTL_CHILD_ kullanılarak geçirilir çünkü simctl launch tüm Xcode sürümlerinde --env/--envs desteklemez.

Örnek:

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

💡 Kullanım Durumu: MCP Tool Çağrıları ile QA Adımı

Bu MCP sunucusu, Model Context Protocol (MCP) istemcisi ile entegre olan yapay zeka asistanlarının tool çağrılarını yaparak Kalite Güvence görevlerini gerçekleştirmesine olanak sağlar. Bu, özelliklerin uygulanmasından hemen sonra UI tutarlılığını ve doğru davranışı sağlamaya yardımcı olmak için faydalıdır.

Nasıl Kullanılır

Bir özellik uygulamasından sonra, MCP istemci ortamındaki yapay zeka asistanına mevcut araçları kullanmasını söyleyin. Örneğin, Cursor'ın agent modunda, UI etkileşimlerini hızlıca doğrulamak ve belgelemek için aşağıda verilen istemi kullanabilirsiniz.

Örnek İstemler

• UI Öğelerini Doğrulayın:

  Geçerli ekrandaki tüm erişilebilirlik öğelerini doğrulayın
  

• Metin Girişini Onaylayın:

  Metin giriş alanına "QA Test" girin ve girişin doğru olduğunu onaylayın
  

• Dokunma Tepkisini Kontrol Edin:

  x=250, y=400 koordinatlarına dokunun ve beklenen öğenin tetiklendiğini doğrulayın
  

• Kaydırma Eylemini Doğrulayın:

  x=150, y=600'den x=150, y=100'e kaydırma yapın ve doğru davranışı onaylayın
  

• Detaylı Öğe Kontrolü:

  x=300, y=350 konumundaki UI öğesini açıklayın ve uygun etiketleme ve işlevselliği sağlayın
  

• AI Ajanınıza Simülatör Ekranını Gösterin:

  Geçerli simülatör ekranını görüntüleyin
  

• Ekran Görüntüsü Alın:

  Geçerli simülatör ekranının ekran görüntüsünü alın ve my_screenshot.png dosyasına kaydedin
  

• Video Kaydı:

  Simülatör ekranının bir video kaydını başlatın (varsayılan çıkış dizinine kaydedilir, bu `~/Downloads` dir; `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` tarafından geçersiz kılınmadıkça)
  

• Kaydı Durdur:

  Geçerli simülatör ekranı kaydını durdurun
  

• Uygulamayı Yükle:

  path/to/MyApp.app konumundaki uygulamayı simülatöre yükleyin
  

• Uygulamayı Başlat:

  Simülatörede Safari uygulamasını (com.apple.mobilesafari) başlatın
  

Ön Koşullar

• Node.js
• macOS (iOS simülatörleri yalnızca macOS'ta kullanılabilir olduğundan)
• Xcode ve iOS simülatörleri yüklenmiş
• Facebook IDB aracı (kurulum rehberine bakın)

Kurulum

Bu bölüm, iOS Simulator MCP sunucusunu farklı Model Context Protocol (MCP) istemcileriyle entegre etmek için talimatlar sağlar.

Cursor ile Kurulum

Cursor, MCP sunucularını ~/.cursor/mcp.json dosyasında bulunan yapılandırma dosyası aracılığıyla yönetir.

Seçenek 1: NPX Kullanma (Önerilen)

1. Cursor MCP yapılandırma dosyasını düzenleyin. Sık sık Cursor'dan doğrudan açabilir veya şu gibi bir komut kullanabilirsiniz:

   # Varsayılan editörle aç (veya 'code', 'vim', vb. kullan)
   open ~/.cursor/mcp.json
   # Veya Cursor'un komutunu kullan (eğer varsa)
   # cursor ~/.cursor/mcp.json
   

2. mcpServers bölümünü iOS simülatörü sunucusu yapılandırmasıyla ekleyin veya güncelleyin:

   {
     "mcpServers": {
       // ... burada diğer sunucular listelenebilir ...
       "ios-simulator": {
         "command": "npx",
         "args": ["-y", "ios-simulator-mcp"]
       }
     }
   }
   

   JSON yapısının geçerli olduğundan emin olun, özellikle mcpServers zaten varsa.
3. Değişikliklerin etkili olması için Cursor'u yeniden başlatın.

Seçenek 2: Yerel Geliştirme

1. Bu depoyu klonlayın:

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

2. Bağımlılıkları yükleyin:

   npm install
   

3. Projeyi derleyin:

   npm run build
   

4. Cursor MCP yapılandırma dosyasını düzenleyin (Seçenek 1'de gösterildiği gibi).
5. mcpServers bölümünü ekleyin veya güncelleyin, yerel derlemelerinize işaret edin:

   {
     "mcpServers": {
       // ... burada diğer sunucular listelenebilir ...
       "ios-simulator": {
         "command": "node",
         "args": ["/full/path/to/your/ios-simulator-mcp/build/index.js"]
       }
     }
   }
   

   Önemli: /full/path/to/your/ öğesini ios-simulator-mcp deposunu klonladığınız mutlak yolla değiştirin.
6. Değişikliklerin etkili olması için Cursor'u yeniden başlatın.

Claude Code ile Kurulum

Claude Code CLI, claude mcp komutlarını kullanarak veya yapılandırma dosyalarını doğrudan düzenleyerek MCP sunucularını yönetebilir. Claude Code MCP yapılandırması hakkında daha fazla ayrıntı için resmi belgelere bakın.

Seçenek 1: NPX Kullanma (Önerilen)

1. claude mcp add komutunu kullanarak sunucuyu ekleyin:

   claude mcp add ios-simulator npx ios-simulator-mcp
   

2. Gerekli olursa çalışan Claude Code oturumlarını yeniden başlatın.

Seçenek 2: Yerel Geliştirme

1. Cursor'un "Yerel Geliştirme" adımlarında 1-3 adımlarında açıklandığı gibi bu depoyu klonlayın, bağımlılıkları yükleyin ve projeyi derleyin.
2. claude mcp add komutunu kullanarak sunucuyu ekleyin, yerel derlemelerinize işaret edin:

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

   Önemli: /full/path/to/your/ öğesini ios-simulator-mcp deposunu klonladığınız mutlak yolla değiştirin.
3. Gerekli olursa çalışan Claude Code oturumlarını yeniden başlatın.

Yapılandırma

Ortam Değişkenleri

Değişken	Açıklama	Örnek
IOS_SIMULATOR_MCP_FILTERED_TOOLS	Kaydedilmekten filtrelenecek araç adlarının virgülle ayrılmış bir listesi.	screenshot,record_video,stop_recording
IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR	Ekran görüntüleri ve video kayıtları gibi çıkış dosyaları için varsayılan bir dizin belirtir. Ayarlanmamışsa ~/Downloads kullanılacaktır. Ajanınız dosya sistemine sınırlı erişime sahipse kullanışlıdır.	~/Code/awesome-project/tmp
IOS_SIMULATOR_MCP_IDB_PATH	IDB yürütülebilirine özel bir yol belirtir. Ayarlanmamışsa idb kullanılacaktır (PATH'inizde olduğu varsayılarak). IDB'nin standart olmayan bir konumda kurulması halinde yararlıdır.	~/bin/idb veya /usr/local/bin/idb

Yapılandırma Örneği

{
  "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"
      }
    }
  }
}

MCP Kayıt Sunucusu Listeleri

Lisans

MIT