Appium MCP Server

A Model Context Protocol (MCP) server that provides Appium mobile automation capabilities to Claude and other MCP-compatible clients.

Features

• Cross-platform mobile automation: Support for both iOS and Android
• Multiple app launch modes: Native apps, browser automation, or installed apps
• Element interaction: Find, tap, and input text to mobile elements
• Session management: Start, monitor, and terminate Appium sessions
• Page inspection: Get page source and scroll functionality
• Easy integration: Works seamlessly with Claude Desktop and other MCP clients

Prerequisites

• Python 3.12+ installed on your system : Environment variable should be set correctly in your bash or zsh so that claude can read it from your system
• Node.js 18.1+ (for npx usage)
• Appium Server running on http://localhost:4723
• Mobile devices/simulators configured and accessible

Setting up Appium Server

# Install Appium globally
npm install -g appium

# Install drivers for your platforms
appium driver install xcuitest     # for iOS
appium driver install uiautomator2 # for Android

# Start Appium server
appium server --port 4723

Installation & Usage

Option 1: Using npx

Add this configuration to your Claude Desktop config file:

{
  "mcpServers": {
    "appium-mcp-server": {
      "command": "npx",
      "args": ["-y", "appium-mcp-server@latest"]
    }
  }
}

Requirements Node.js >= 18 installed globally npx available in PATH

🔹 2. ⚠️ Important note (THIS IS KEY)

> ⚠️ Note:
> If you are using Node via NVM, Claude Desktop may not detect it automatically.
> In that case, use Option 2 below.

### Option 2: NVM Users (Recommended if Option 1 fails)

```json
{
  "mcpServers": {
    "appium-mcp-server": {
      "command": "bash",
      "args": [
        "-lc",
        "export NVM_DIR=\"$HOME/.nvm\" && source \"$NVM_DIR/nvm.sh\" && npx -y appium-mcp-server@latest"
      ]
    }
  }
}

Option 3: NVM Users (Recommended if Option 2 fails)

{
  "mcpServers": {
    "appium-mcp-server": {
      "command": "bash",
      "args": [
        "-lc",
        "export NVM_DIR=\"$HOME/.nvm\" && [ -s \"/opt/homebrew/opt/nvm/nvm.sh\" ] && . \"/opt/homebrew/opt/nvm/nvm.sh\" && nvm use 20 >/dev/null && npx -y appium-mcp-server@latest"
      ]
    }
  }
}

🔹 4. 💪 Advanced / stable (BEST for reliability)

### Option 3: Use Node directly (Most reliable)

```json
{
  "mcpServers": {
    "appium-mcp-server": {
      "command": "/path/to/your/node",
      "args": [
        "/path/to/appium-mcp-server/bin/appium-mcp-server.js"
      ]
    }
  }
}

To find your Node path: which node

🧠 Why this is the BEST approach

You cover:

| User type | Works? | |----------|--------| | Beginner | ✅ npx | | NVM user | ✅ bash fix | | Power user | ✅ direct node |

Option 4: VS Code Local Setup (Github Copilot / Cursor)

If you want to use appium-mcp-server with GitHub Copilot or Cursor inside your existing VS Code project, follow these steps:

At the root of your existing project, create a .vscode folder (if it doesn't exist) and inside it create a file named mcp.json:

your-existing-project/
└── .vscode/
    └── mcp.json

Paste the following into mcp.json:

{
  "servers": {
    "appium-mcp-prod": {
      "command": "/Users/username/appium-mcp-server/.venv/bin/python",
      "args": ["src/mcp_server.py"],
      "cwd": "~/appium-mcp-server",
      "env": {
        "APPIUM_PORT": "4723"
      }
    }
  }
}

⚠️ Replace /Users/username/ with the actual path where you cloned appium-mcp-server.
Run pwd inside the cloned folder to get the exact path.

⚙️ Local System Setup Instructions for Apple M1/M2 and Windows

🍎 Apple Silicon (M1/M2) – macOS

Apple Silicon users must rebuild the Python virtual environment (.venv) locally to avoid architecture compatibi

... View full README on GitHub