MCP Appium Server

🚀 MCP Appium Server

A Node.js server that exposes mobile automation capabilities as MCP tools for LLM agents.

🚀 Quick Start

The MCP Appium Server is a Node.js server that provides mobile automation capabilities as MCP tools for LLM agents. It allows you to describe what you want to test in natural language, and the LLM agent will interact with the mobile app accordingly.

✨ Features

• MCP Compatibility: Follows the Model Context Protocol (MCP) spec for tool registration and uses stdio transport.
• LLM - Controlled Automation: Enables LLM agents to interact with mobile apps using natural language.
• Multiple Tools: Provides 6 production - ready MCP tools for mobile automation.
• Safe and Reliable: Safe for autonomous agents with no destructive commands, graceful error handling, and session validation.
• Production - Quality: Comprehensive logging, TypeScript strict mode, and graceful shutdown with cleanup.

📦 Installation

Prerequisites

1. Node.js 18+

   node --version  # Should be >= 18.0.0
   

2. Appium 2.x

   npm install -g appium
   appium driver install uiautomator2  # For Android
   appium driver install xcuitest      # For iOS
   

3. Android Setup (for Android testing)
   • Android SDK installed
   • Emulator or physical device available
   • adb devices shows your device
4. iOS Setup (for iOS testing)
   • Xcode installed (macOS only)
   • iOS Simulator available
   • Xcode Command Line Tools installed

Installation Steps

1. Clone and install dependencies:

   cd mcp-appium-server
   npm install
   

2. Build TypeScript:

   npm run build
   

3. Test the server (optional):

   npm start
   # Server will start and listen on stdio
   # Press Ctrl+C to stop
   

💻 Usage Examples

Option 1: Direct Execution

node dist/index.js

The server will:

• Start listening on stdio
• Auto - launch Appium when the first session is created
• Handle graceful shutdown on SIGINT/SIGTERM

Option 2: MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop, custom LLM agent) to use this server:

Example MCP config (~/.mcp/config.json):

{
  "mcpServers": {
    "appium": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-appium-server/dist/index.js"],
      "env": {}
    }
  }
}

Example LLM Conversation

User: "Start an Android session for the Calculator app, then tap the number 5 button"

LLM Agent (internal reasoning):

1. Call create_mobile_session with Android capabilities
2. Receive sessionId
3. Call tap_element with selector for "5" button
4. Return success to user

Result: The calculator app opens and "5" is tapped autonomously.

📚 Documentation

What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It acts as a universal adapter that allows AI agents like GPT - 4 or Claude to interact with external tools and services.

Key Concepts

• MCP Server: A program that exposes capabilities (tools, resources, prompts) to LLM agents
• MCP Client: An LLM agent or application that consumes these capabilities
• Tools: Functions that an LLM can call to perform actions (e.g., click a button, type text)
• stdio Transport: Communication over standard input/output (perfect for local execution)

Why MCP for Mobile Automation?

Instead of writing imperative test scripts, you describe what you want to test in natural language. The LLM agent:

1. Understands your intent
2. Calls MCP tools to interact with the mobile app
3. Observes the results (screenshots, element states)
4. Makes decisions autonomously
5. Provides human - readable reports

This is not a test framework — it's an LLM - controlled mobile automation control plane.

Architecture

┌─────────────────────────────────────┐
│   LLM Agent (GPT-4 / Claude)        │
│   "Tap the login button"            │
└────────────┬────────────────────────┘
             │ MCP Protocol
             │ (stdio)
             ▼
┌─────────────────────────────────────┐
│   MCP Appium Server (Node.js)       │
├─────────────────────────────────────┤
│  • Tool Registry (6 tools)          │
│  • Session Manager (stateful)       │
│  • Appium Launcher                  │
│  • Command Executor (WebdriverIO)   │
└────────────┬────────────────────────┘
             │ WebDriver Protocol
             ▼
┌─────────────────────────────────────┐
│   Appium Server (2.x)               │
└────────────┬────────────────────────┘
             │
             ▼
┌─────────────────────────────────────┐
│   Android Emulator / iOS Simulator  │
└─────────────────────────────────────┘

MCP Tools

This server exposes 6 production - ready MCP tools:

1. create_mobile_session

Purpose: Create an Appium session for Android or iOS

Input:

{
  "platform": "android | ios",
  "capabilities": {
    "deviceName": "Pixel_5_API_31",
    "app": "/path/to/app.apk",
    "automationName": "UiAutomator2"
  }
}

Output:

{
  "success": true,
  "sessionId": "abc123...",
  "platform": "android"
}

2. tap_element

Purpose: Tap/click on a UI element

Input:

{
  "sessionId": "abc123...",
  "strategy": "id | xpath | accessibilityId",
  "selector": "com.example:id/login_button"
}

3. type_text

Purpose: Type text into an element

Input:

{
  "sessionId": "abc123...",
  "strategy": "accessibilityId",
  "selector": "username_field",
  "text": "testuser@example.com"
}

4. navigate_back

Purpose: Press back button (Android) or navigate back (iOS)

Input:

{
  "sessionId": "abc123..."
}

5. take_screenshot

Purpose: Capture current screen state

Input:

{
  "sessionId": "abc123..."
}

Output:

{
  "success": true,
  "imageBase64": "iVBORw0KGgoAAAANSUhEU...",
  "format": "png"
}

6. close_mobile_session

Purpose: Close session and cleanup

Input:

{
  "sessionId": "abc123..."
}

Project Structure

mcp-appium-server/
├── src/
│   ├── index.ts                  # Entry point, signal handlers
│   ├── mcp/
│   │   ├── server.ts             # MCP server setup & tool registry
│   │   └── tools.ts              # Tool implementations
│   ├── appium/
│   │   ├── appiumLauncher.ts     # Start/stop Appium process
│   │   ├── sessionManager.ts     # Session lifecycle & state
│   │   └── commandExecutor.ts    # WebDriver command mapping
│   └── types/
│       └── toolSchemas.ts        # JSON schemas for tools
├── package.json
├── tsconfig.json
└── README.md

Design Principles

1. MCP - Compliant

• Follows MCP spec for tool registration
• Uses stdio transport
• Structured errors with error codes

2. Stateless Tools, Stateful Sessions

• Each tool call is idempotent
• Session state managed in - memory
• Session IDs passed explicitly

3. Safe for Autonomous Agents

• No destructive commands exposed
• Graceful error handling
• Session validation on every call

4. Production - Quality

• Comprehensive logging (Winston)
• TypeScript strict mode
• Graceful shutdown with cleanup

Error Handling

All errors are returned as MCP - compatible structured errors:

{
  "error": {
    "code": "InternalError",
    "message": "Session not found: xyz123. Create a session first using create_mobile_session."
  }
}

Common Errors:

• Session not found: Call create_mobile_session first
• Element not found: Check your selector strategy/value
• Appium startup timeout: Ensure Appium is installed and in PATH

Known Limitations

1. Local Execution Only: No cloud device farm support (yet)
2. stdio Transport Only: No WebSocket/HTTP support (yet)
3. Basic Element Interaction: No gestures (swipe, pinch) yet
4. No Accessibility Tree Export: Coming in future versions
5. No Vision Integration: Screenshot analysis requires external LLM vision

Future Extensions

• 🔄 Gesture support (swipe, scroll, pinch)
• 🌳 Accessibility tree export for better element discovery
• 📸 Vision API integration for screenshot analysis
• 🌐 WebSocket transport for remote execution
• ☁️ Cloud device farm support (BrowserStack, Sauce Labs)
• 🔍 Enhanced element discovery with AI - powered selectors

Troubleshooting

"Appium startup timeout"

Solution: Ensure Appium is installed globally:

npm install -g appium
appium --version

"Session creation failed"

Solution: Check device availability:

# Android
adb devices

# iOS
xcrun simctl list devices

"Element not found"

Solution: Take a screenshot first to verify element visibility:

{
  "tool": "take_screenshot",
  "input": { "sessionId": "..." }
}

📄 License

ISC

Credits

Built with:

• @modelcontextprotocol/sdk - MCP protocol implementation
• Appium - Mobile automation framework
• WebdriverIO - WebDriver client
• Winston - Logging

Questions? Check out the Model Context Protocol documentation or open an issue.