Servidor MCP Appium

Una implementación de servidor de Protocolo de Contexto de Modelo (MCP) para la automatización de aplicaciones móviles utilizando Appium.

Prerrequisitos

Node.js (v14 o superior)
Kit de desarrollo de Java (JDK)
SDK de Android (para pruebas de Android)
Xcode (solo para pruebas de iOS, macOS)
Servidor Appium
Dispositivo o emulador Android / dispositivo o simulador iOS

Configuración del entorno

Antes de ejecutar cualquier comando, asegúrese de que las variables de entorno estén configuradas correctamente:

Asegúrese de que su .bash_profile , .zshrc u otro archivo de configuración de shell contenga las variables de entorno necesarias:

# Example environment variables in ~/.bash_profile
export JAVA_HOME=/path/to/your/java
export ANDROID_HOME=/path/to/your/android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

Obtenga el archivo de su entorno antes de ejecutar MCP-Appium:

source ~/.bash_profile  # For bash
# OR
source ~/.zshrc         # For zsh

Nota : El sistema intentará obtener su .bash_profile automáticamente al inicializar el controlador, pero se recomienda asegurar la configuración adecuada del entorno manualmente antes de ejecutar pruebas en una nueva sesión de terminal.

Configuración de las herramientas de línea de comandos de Xcode

Para las pruebas de iOS, es esencial configurar adecuadamente las herramientas de línea de comandos de Xcode:

Instale las herramientas de línea de comandos de Xcode si aún no están instaladas:

xcode-select --install

Verifique la instalación y verifique la ruta actual de Xcode:

xcode-select -p

Si es necesario, configure la ruta Xcode correcta (especialmente si tiene varias versiones de Xcode):

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Aceptar los acuerdos de licencia de Xcode:

sudo xcodebuild -license accept

Para realizar pruebas en dispositivos iOS reales, asegúrese de que su cuenta de desarrollador de Apple esté configurada correctamente en Xcode:
- Abrir Xcode
- Vaya a Preferencias > Cuentas
- Añade tu ID de Apple si aún no lo has hecho
- Descargue los perfiles de aprovisionamiento necesarios
Configurar variables de entorno para el desarrollo de iOS:

# Add these to your ~/.bash_profile or ~/.zshrc
export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
export PATH="$DEVELOPER_DIR/usr/bin:$PATH"

Obtenga su configuración actualizada:

source ~/.bash_profile  # For bash
# OR
source ~/.zshrc         # For zsh

Configuración

Instalar dependencias:

npm install

Instalar e iniciar el servidor Appium:

npm install -g appium
appium

Configurar el dispositivo/emulador de Android:
- Habilite las opciones de desarrollador en su dispositivo Android
- Habilitar la depuración USB
- Conecte el dispositivo a través de USB o inicie un emulador
- Verifique que el dispositivo esté conectado mediante adb devices
Para pruebas de iOS (solo macOS):
- Asegúrese de que las herramientas de línea de comandos de Xcode estén instaladas: xcode-select --install
- Configurar el simulador de iOS o conectar un dispositivo real
- Confíe en la computadora de desarrollo en el dispositivo iOS si usa un dispositivo real

Ejecución de pruebas

Construir el proyecto:

npm run build

Inicie el servidor MCP:

npm run dev

En una nueva terminal, ejecute la prueba:

npm test

Configuración de prueba

Configuración de Android

La prueba de ejemplo utiliza la aplicación Ajustes de Android como demostración. Para probar tu propia aplicación:

Editar examples/appium-test.ts :
- Actualice deviceName para que coincida con su dispositivo
- Establezca la ruta app en su archivo APK, o
- Actualizar appPackage y appActivity para una aplicación instalada
Configuración de capacidades comunes:

const capabilities: AppiumCapabilities = {
  platformName: "Android",
  deviceName: "YOUR_DEVICE_NAME",
  automationName: "UiAutomator2",
  // For installing and testing an APK:
  app: "./path/to/your/app.apk",
  // OR for testing an installed app:
  appPackage: "your.app.package",
  appActivity: ".MainActivity",
  noReset: true,
};

Configuración de iOS

Para probar iOS usando la nueva compatibilidad con la línea de comandos de Xcode:

Ejemplo de configuración en examples/xcode-appium-example.ts :

const capabilities: AppiumCapabilities = {
  platformName: "iOS",
  deviceName: "iPhone 13", // Your simulator or device name
  automationName: "XCUITest",
  udid: "DEVICE_UDID", // Get this from XcodeCommands.getIosSimulators()
  // For installing and testing an app:
  app: "./path/to/your/app.app",
  // OR for testing an installed app:
  bundleId: "com.your.app",
  noReset: true,
};

Acciones disponibles

El servidor MCP admite varias acciones de Appium:

Interacciones de elementos:
- Encontrar elementos
- Tocar o hacer clic en elementos con la API de acciones del W3C (consulte la sección "Gestos estándar del W3C")
- Escribe texto
- Desplazarse al elemento con la API de acciones W3C
- Pulsación larga
Gestión de aplicaciones:
- Iniciar/cerrar la aplicación
- Restablecer la aplicación
- Obtener paquete/actividad actual
Controles del dispositivo:
- Orientación de la pantalla
- Manejo del teclado
- Bloqueo/desbloqueo del dispositivo
- Capturas de pantalla
- Información de la batería
Funciones avanzadas:
- Cambio de contexto (Nativo/WebView)
- Operaciones con archivos
- Notificaciones
- Gestos personalizados
Herramientas de línea de comandos de Xcode (solo iOS):
- Administrar simuladores de iOS (arranque, apagado)
- Instalar/desinstalar aplicaciones en simuladores
- Iniciar/cerrar aplicaciones
- Tomar capturas de pantalla
- Grabar vídeos
- Crear/eliminar simuladores
- Obtener tipos de dispositivos y tiempos de ejecución

Gestos estándar del W3C

La biblioteca MCP-Appium ahora implementa la API W3C WebDriver Actions para gestos táctiles, que es el estándar moderno para la automatización móvil.

Acciones del W3C para elementos Tap

El método tapElement ahora utiliza la API de acciones W3C con alternativas inteligentes:

// The method will try in this order:
// 1. Standard WebdriverIO click()
// 2. W3C Actions API
// 3. Legacy TouchAction API (fallback for backward compatibility)
await appium.tapElement("//android.widget.Button[@text='OK']");
// or using the click alias
await appium.click("//android.widget.Button[@text='OK']");

Acciones del W3C para el desplazamiento

El método scrollToElement ahora utiliza la API de acciones W3C:

// Uses W3C Actions API for more reliable scrolling
await appium.scrollToElement(
  "//android.widget.TextView[@text='About phone']", // selector
  "down", // direction: "up", "down", "left", "right"
  "xpath", // strategy
  10 // maxScrolls
);

Gestos personalizados del W3C

Puede crear sus propios gestos W3C personalizados utilizando el método executeMobileCommand :

// Create custom W3C Actions API gesture
const w3cActions = {
  actions: [
    {
      type: "pointer",
      id: "finger1",
      parameters: { pointerType: "touch" },
      actions: [
        // Move to start position
        { type: "pointerMove", duration: 0, x: startX, y: startY },
        // Press down
        { type: "pointerDown", button: 0 },
        // Move to end position over duration milliseconds
        {
          type: "pointerMove",
          duration: duration,
          origin: "viewport",
          x: endX,
          y: endY,
        },
        // Release
        { type: "pointerUp", button: 0 },
      ],
    },
  ],
};

// Execute the W3C Actions using executeScript
await appium.executeMobileCommand("performActions", [w3cActions.actions]);

Consulte examples/w3c-actions-swipe-demo.ts para obtener más ejemplos de implementaciones de gestos estándar del W3C.

Uso de las herramientas de línea de comandos de Xcode

La nueva clase XcodeCommands proporciona herramientas potentes para las pruebas de iOS:

import { XcodeCommands } from "../src/lib/xcode/xcodeCommands.js";

// Check if Xcode CLI tools are installed
const isInstalled = await XcodeCommands.isXcodeCliInstalled();

// Get available simulators
const simulators = await XcodeCommands.getIosSimulators();

// Boot a simulator
await XcodeCommands.bootSimulator("SIMULATOR_UDID");

// Install an app
await XcodeCommands.installApp("SIMULATOR_UDID", "/path/to/app.app");

// Launch an app
await XcodeCommands.launchApp("SIMULATOR_UDID", "com.example.app");

// Take a screenshot
await XcodeCommands.takeScreenshot("SIMULATOR_UDID", "/path/to/output.png");

// Shutdown a simulator
await XcodeCommands.shutdownSimulator("SIMULATOR_UDID");

Uso de la función de clic

El método click() proporciona una alternativa más intuitiva a tapElement() :

// Using the click method
await appium.click("//android.widget.Button[@text='OK']");

// This is equivalent to:
await appium.tapElement("//android.widget.Button[@text='OK']");

Solución de problemas

Dispositivo no encontrado:
- Comprobar la salida de adb devices
- Verifique que la depuración USB esté habilitada
- Intente volver a conectar el dispositivo
La aplicación no se instala:
- Verificar que la ruta del APK sea correcta
- Compruebe que el dispositivo tenga suficiente almacenamiento
- Asegúrese de que la aplicación esté firmada para depuración
Elementos no encontrados:
- Utilice Appium Inspector para verificar los selectores
- Comprobar si los elementos son visibles en la pantalla
- Pruebe diferentes estrategias de localización
Problemas de conexión:
- Verifique que el servidor Appium esté en ejecución
- Comprobar conflictos de puertos
- Asegúrese de que se configuren las capacidades correctas
Problemas con el simulador de iOS:
- Verifique que las herramientas de línea de comandos de Xcode estén instaladas: xcode-select -p
- Compruebe que el UDID del simulador sea correcto usando xcrun simctl list devices
- Cierre y reinicie el simulador si deja de responder.

Contribuyendo

No dudes en enviar problemas y solicitudes de extracción para funciones adicionales o correcciones de errores.

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite la automatización de aplicaciones móviles mediante Appium, admitiendo diversas interacciones de dispositivos, operaciones de elementos y gestión de aplicaciones a través de un protocolo estandarizado.

Related Resources

Reddit Discussion about this server

Related MCP Servers

ABAP-ADT-API MCP-Server
mario-andreschak
A
security
A
license
A
quality
A Model Context Protocol server that facilitates communication between ABAP systems and MCP clients, providing tools for managing ABAP objects, handling transport requests, and performing code analysis to enhance ABAP development workflows.
Last updated -
55
MIT License
DroidMind
hyperb1iss
A
security
A
license
A
quality
A Model Context Protocol (MCP) server that enables AI assistants to control and interact with Android devices, allowing for device management, app debugging, system analysis, and UI automation through natural language commands.
Last updated -
8
236
Apache 2.0
Mobile Next MCP Serverofficial
mobile-next
A
security
A
license
A
quality
A Model Context Protocol server that enables scalable mobile automation through a platform-agnostic interface for iOS and Android devices, allowing agents and LLMs to interact with mobile applications using accessibility snapshots or coordinate-based interactions.
Last updated -
17
4,953
2,034
Apache 2.0
Mobile Next MCP
EmpathySlainLovers
A
security
A
license
A
quality
A Model Context Protocol server that enables scalable mobile automation for iOS and Android through a platform-agnostic interface, allowing LLMs to interact with mobile applications via accessibility snapshots or screenshot-based inputs.
Last updated -
17
4,953
1
Apache 2.0

View all related MCP servers

MCP Appium Server