Mobile Automation MCP Server

🚀 モバイル自動化iOS MCPサーバー

FastMCP 2.0とクリーンなアーキテクチャで構築された、最新のiOS自動化サーバー

FastMCP 2.0を使用して構築された、本番環境で使用可能なiOS自動化MCPサーバーです。クリーンなモジュールアーキテクチャを備え、完全なプラットフォーム分離が実現されています。iOS固有のコンポーネントと共有コンポーネントが適切に分離されており、クロスプラットフォーム拡張に対応しています。

📺 デモビデオ

🎬 完全なデモを見る: Mobile automation iOS MCP server in Action

✨ 主な機能

• 🚀 FastMCP 2.0 - 最新のPythonベースのMCP実装
• 🌐 クラウドデプロイメント - Railway、Heroku、または他のプラットフォームでのデプロイに対応
• 📱 実際のiOS自動化 - AppiumとWebDriverAgentの統合
• 🏗️ クリーンなモジュールアーキテクチャ - 完全なプラットフォーム分離とSOLID原則の適用
• 🔄 クロスプラットフォーム対応 - 将来のAndroidや他のプラットフォーム用の共有ユーティリティ
• 🎨 美しいロギング - 絵文字付きのカラーコンソール出力
• 🔧 型安全 - 全体にわたる包括的な型ヒント
• 🔌 拡張可能 - モジュール構成によるプラグインスタイルのツールシステム
• 📦 コードの重複ゼロ - 共有ユーティリティによるDRY原則の適用

🚀 クイックスタート

オプション1: リモートサーバー (推奨)

Railwayでホストされているバージョンを使用します - ローカルセットアップは不要です。

{
  "mcpServers": {
    "ios-automation-railway": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-server-demo-production.up.railway.app/sse/"
      ]
    }
  }
}

オプション2: ローカル開発

1. 前提条件

   • macOS (iOS自動化に必要)
   • Python 3.11以上
   • uv (推奨) またはpip
   • iOSシミュレーター付きのXcode
   • Node.js (Appium用)

2. インストール

   git clone https://github.com/iHackSubhodip/mcp-server-demo.git
   cd mcp-server-demo
   
   # uvを使用する場合 (推奨)
   uv sync
   
   # またはpipを使用する場合 (旧来の方法)
   pip install -e .
   

3. Claude Desktopの設定

   {
     "mcpServers": {
       "ios-automation-local": {
         "command": "uv",
         "args": ["run", "python", "mobile-automation-mcp-server/fastmcp_server.py"],
         "cwd": "/path/to/mcp-server-demo"
       }
     }
   }
   

🏗️ アーキテクチャ

モバイル自動化iOS MCPサーバーは、包括的な6段階のリファクタリングにより、クリーンでモジュール化されたアーキテクチャを備えており、完全なプラットフォーム分離が実現されています。この設計により、最大限の保守性、コードの重複ゼロ、およびシームレスなクロスプラットフォーム拡張が可能になります。

✨ アーキテクチャの成果

🎯 完全なプラットフォーム分離

• クロスプラットフォームユーティリティ は shared/ パッケージに分離されています。
• iOS固有のコード は platforms/ios/ パッケージに含まれています。
• すべてのコンポーネントで 明確な分離 が実現されています。
• platforms/android/ でのAndroid対応に 将来対応 しています。

🔄 DRY原則の適用

• 共有ユーティリティ: ロガー、例外、コマンドランナー
• 基本設定: AppiumConfig、ServerConfigの再利用
• プラットフォーム設定: iOS固有の設定は分離されています。
• 現在および将来のプラットフォーム間で コードの重複ゼロ です。

🛡️ 保守性と拡張性

• 自己完結型のプラットフォーム: 各プラットフォームは完全に独立しています。
• 統一インターフェース: 単一の設定エントリポイント
• 下位互換性: すべての既存のインターフェースが保持されています。
• プロフェッショナルな構造: エンタープライズグレードの組織化

ディレクトリ構造

mobile-automation-mcp-server/
├── fastmcp_server.py          # 🚀 FastMCP 2.0サーバー (メインエントリ)
├── config/
│   └── settings.py           # 🔧 統一設定インターフェース
├── shared/                   # 🌐 クロスプラットフォームユーティリティと設定
│   ├── utils/               # 🛠️ プラットフォームに依存しないユーティリティ  
│   │   ├── logger.py       # 📝 絵文字付きのカラーロギング
│   │   ├── exceptions.py   # ⚠️ 例外階層
│   │   └── command_runner.py # 💻 シェルコマンド実行
│   └── config/             # ⚙️ 基本設定クラス
│       └── base_settings.py # 📋 AppiumConfig、ServerConfig
├── platforms/ios/          # 🍎 iOS固有のプラットフォームコード
│   ├── automation/         # 🤖 iOS自動化サービス
│   │   ├── appium_client.py # 📱 iOS自動化クライアント
│   │   ├── screenshot_service.py # 📸 スクリーンショット処理
│   │   └── simulator_manager.py # 🎮 シミュレーター管理
│   ├── tools/             # 🔨 iOS固有のMCPツール
│   │   ├── appium_tap_type_tool.py # ⌨️ テキストフィールド自動化
│   │   ├── find_and_tap_tool.py    # 👆 高度な要素検索
│   │   ├── launch_app_tool.py      # 🚀 アプリ起動
│   │   └── screenshot_tool.py      # 📷 スクリーンショット取得
│   └── config/            # ⚙️ iOS固有の設定
│       └── ios_settings.py # 🍎 iOSConfig (XCUITest、iPhone)
├── screenshots/             # 📁 スクリーンショット保存先
├── Dockerfile              # 🐳 コンテナデプロイメント
├── Procfile                # 🚂 Railwayデプロイメント
└── pyproject.toml          # 📦 依存関係とプロジェクト設定

🎯 成果の比較

🔧 利用可能なツール

take_screenshot

iOSシミュレーターのスクリーンショットを取得します。

{
  "filename": "optional_name.png",
  "device_id": "booted"
}

launch_app

iOSアプリケーションを起動します。

{
  "bundle_id": "com.apple.mobilesafari",
  "device_id": "booted"
}

find_and_tap

スマートな自動化でUI要素を検索してタップします。

{
  "accessibility_id": "submitButton",
  "take_screenshot": true,
  "dismiss_after_screenshot": false
}

appium_tap_and_type

要素検索を伴う強化されたテキスト入力を行います。

{
  "text": "Hello World!",
  "element_type": "textField",
  "timeout": 10
}

list_simulators

利用可能なiOSシミュレーターを一覧表示します。

{}

get_server_status

サーバーとAppiumのステータスを確認します。

{}

🛠️ 開発

ローカル開発コマンド

# ローカルでFastMCPサーバーを実行する (uvを使用)
uv run python mobile-automation-mcp-server/fastmcp_server.py

# 依存関係をインストールする (必要な場合)
uv sync

# 開発モードで実行する (開発用依存関係を含む)
uv sync --dev

Appiumのセットアップ

# Appiumをインストールする
npm install -g appium
appium driver install xcuitest

# Appiumサーバーを起動する
appium server --port 4723

アーキテクチャ開発

# モジュール構造により開発が容易になります。

# 共有ユーティリティを開発する (すべてのプラットフォームに影響する)
cd shared/utils/

# iOS固有の機能を開発する  
cd platforms/ios/

# 設定を開発する
cd config/

# 新しいプラットフォームを追加する (将来的な対応)
mkdir platforms/android/

🌐 クラウドデプロイメント

このサーバーはRailwayでデプロイされており、以下のエンドポイントからアクセスできます。

• HTTPエンドポイント: https://mcp-server-demo-production.up.railway.app/
• SSEエンドポイント: https://mcp-server-demo-production.up.railway.app/sse/

クラウドデプロイメントは、デモ目的でiOS自動化の応答をシミュレートします。

📊 主な改善点

🔍 トラブルシューティング

シミュレーターの問題

# 利用可能なシミュレーターを一覧表示する
xcrun simctl list devices

# シミュレーターを起動する
xcrun simctl boot "iPhone 16 Pro"

Appiumの接続

# Appiumのステータスを確認する
curl http://localhost:4723/status

# Appiumを再起動する
pkill -f appium && appium server --port 4723

📝 依存関係

主要な依存関係は pyproject.toml で管理されています。

• fastmcp>=2.9.2 - FastMCP 2.0フレームワーク
• mcp>=1.0.0 - 従来のMCPプロトコル
• aiohttp>=3.9.0 - 自動化用のHTTPクライアント
• appium-python-client>=3.0.0 - iOS自動化
• pydantic>=2.4.0 - データ検証

以下のコマンドでインストールします。

# uvを使用する場合 (推奨)
uv sync

# またはpipを使用する場合
pip install -e .

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. クリーンなアーキテクチャパターンに従います。
   • 共有ユーティリティ は shared/ に配置します。
   • プラットフォーム固有のコード は platforms/{platform}/ に配置します。
   • 設定 はモジュール化された階層に従います。
4. 包括的なエラーハンドリングを追加します。
5. プルリクエストを送信します。

🚀 将来の拡張

クリーンなアーキテクチャのおかげで、新しいプラットフォームの追加は簡単です。

# Androidプラットフォームを追加する (例)
mkdir -p platforms/android/{automation,tools,config}

# 共有ユーティリティを再利用する
from shared.utils import get_logger, AutomationMCPError
from shared.config import AppiumConfig, ServerConfig

# Android固有の設定を作成する
from platforms.android.config import AndroidConfig

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています - 詳細については LICENSE ファイルを参照してください。