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 compatibility errors like:

ImportError: ... incompatible architecture (have 'x86_64', need 'arm64')

✅ Steps for M1/M2 Macs:

• 🧬 Clone the project
• 📂 Open Terminal
• Navigate to your project repository
• 🛠️ Run: chmod +x bootstrap.sh
• 🛠️ Run: ./bootstrap.sh
  • 🧹 Removes the prebuilt .venv
  • 🧱 Recreates .venv using native arm64 Python
  • 📦 Reinstalls all Python dependencies
• 🔁 You only need to do this once, unless .venv is deleted or requirements.txt changes

---

💻 Windows Users

Windows users can use the bundled .venv if compatible, or regenerate it locally.

✅ Steps for Windows:

• 🧬 Clone the project
• 📂 Open Command Prompt or PowerShell
• 📁 Navigate to your project folder (e.g. cd C:\Users\YourName\appium-mcp-server)
• 🛠️ Run: bootstrap.bat
  • 🧱 Creates a fresh .venv using your system’s Python (≥ 3.10)
  • 📦 Installs all dependencies from requirements.txt
• 🛑 Make sure Python is in your PATH and is version ≥ 3.10

---

🧪 Verify It Works

🧪 Starting the Server

After running the appropriate setup script (./bootstrap.sh on macOS or bootstrap.bat on Windows), start the MCP server using either of the following:

npx appium-mcp-server

Or run it directly from project path:

node bin/appium-mcp-server.js

You should see output like:
🚀 Starting MCP server using python3.12
🔧 Injecting PYTHONPATH = ...

### 🧪 Using Claude Desktop with a Local Project

To run your **local version** of the MCP server with Claude Desktop, follow these steps:

1. Open **Claude Desktop**
2. Go to **Settings → Developer → EditConfig button
3. This will open the `desktip-claude-config.json` file
4. Add the following configuration under `"mcpServers"`:

---

#### 🍎 macOS (Intel or Apple Silicon)

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

💻 Windows
{
  "mcpServers": {
    "local-appium-mcp": {
      "command": "node",
      "args": ["C:\\Users\\your.name\\appium-mcp-server\\bin\\appium-mcp-server.js"]
    }
  }
}

📝 Replace /Users/your.name/... with the full path to your cloned project directory.


## Available Tools

### Session Management

- **`appium_start_session`**: Start an Appium session
  - `platform`: "iOS" or "Android"
  - `device_name`: Device name or UDID
  - `app_path`: Path to app file (optional)
  - `bundle_id`: iOS bundle ID (optional)
  - `app_package`: Android package name (optional)
  - `app_activity`: Android activity (optional)

- **`appium_get_session_info`**: Get current session information
- **`appium_quit_session`**: Terminate the current session

### Element Interaction

- **`appium_find_element`**: Find elements on screen
  - `strategy`: "id", "xpath", "class_name", or "accessibility_id"
  - `value`: Locator value

- **`appium_tap_element`**: Tap on an element
  - `element_id`: ID of previously found element

- **`appium_input_text`**: Send text to input fields
  - `element_id`: Target element ID
  - `text`: Text to input

### Page Navigation

- **`appium_get_page_source`**: Get current page source
- **`appium_scroll`**: Scroll the screen
  - `direction`: "up" or "down"

## Example Usage with Claude

Start an iOS session on iPhone 15 Pro Max simulator, then navigate to the SauceDemo website and automate the login process.

Claude will use the MCP server to:
1. Start an Appium session
2. Find login elements
3. Input credentials
4. Navigate through the app

## Configuration Examples

### iOS Safari Browser Testing
```json
{
  "platform": "iOS",
  "device_name": "iPhone 15 Pro Max"
}

Android Chrome Browser Testing

{
  "platform": "Android", 
  "device_name": "Android Emulator"
}

iOS Native App Testing

{
  "platform": "iOS",
  "device_name": "iPhone 15 Pro Max",
  "bundle_id": "com.example.myapp"
}

Android Native App Testing

{
  "platform": "Android",
  "device_name": "Android Emulator",
  "app_package": "com.example.myapp",
  "app_activity": ".MainActivity"
}

🚀 Quick Start with Gemini CLI

The easiest way to run mobile automation commands is using our simple CLI wrapper with Gemini.

Setup Instructions

• 🧬 Clone the project
• 📂 Open Terminal
• Navigate to your project repository
• Also make sure you have created .env file in your project root and entered GEMINI_API_KEY key there

Load environment variables from .env

load_dotenv()

Get the API key

api_key = os.getenv("GEMINI_API_KEY")

1. Make the setup script executable:

   chmod +x mobile-setup.sh
   

2. Load the mobile function:

   source mobile-setup.sh
   

   You should see:

   Mobile automation function loaded!
   Usage: mobile "Launch Settings on iPhone"
          mobile -i
          mobile --claude "Open Instagram"
   
   To make this permanent, add this to your ~/.bashrc or ~/.zshrc:
   source "/path/to/your/mobile-setup.sh"
   

3. Test the function:

   # Test help
   mobile -h
   
   # Test interactive mode
   mobile -i
   
   # Test single command
   mobile "Launch Settings on iPhone"
   
   # Test with Claude
   mobile --claude "Open Instagram and scroll down"
   

Make it Permanent (Optional)

To have the mobile function available every time you open a terminal:

For Bash users:

echo "source $(pwd)/mobile-setup.sh" >> ~/.bashrc

For Zsh users:

echo "source $(pwd)/mobile-setup.sh" >> ~/.zshrc

For Fish shell users:

mkdir -p ~/.config/fish/functions
# Then manually create the fish function file

Usage Examples

# Single prompts (default Gemini)
mobile "Launch Settings on iPhone 15 Pro Max"
mobile "Open Instagram and like the first post"
mobile "Calculate 15 + 25 in Calculator app"
mobile "Launch Safari and go to google.com"

# Single prompts with Claude
mobile --claude "Open Notes and create a new note"
mobile --claude "Launch Camera and take a photo"

# Interactive modes
mobile -i                    # Interactive with Gemini
mobile --claude -i           # Interactive with Claude
mobile --interactive         # Interactive with Gemini

# Help
mobile -h
mobile --help

For Windows:

Run the setup script: cmdmobile-setup.bat You should see: Mobile automation command created!

Usage: mobile "Launch Settings on iPhone" mobile -i mobile --claude "Open Instagram"

The 'mobile' command is now available for this session. You should see: Mobile automation function loaded! Usage: mobile "Launch Settings on iPhone" mobile -i mobile --claude "Open Instagram"

To make this permanent, add this to your ~/.bashrc or ~/.zshrc: source "/path/to/your/mobile-setup.sh"

Test the function: bash# Test help mobile -h

Test interactive mode

mobile -i

Test single command

mobile "Launch Settings on iPhone"

Test with Claude

mobile --claude "Open Instagram and scroll down"

Make it Permanent (Optional) For Windows: Command Prompt:

Add the script directory to your system PATH, or Run mobile-setup.bat each time you open a new command prompt

Usage Examples bash# Single prompts (default Gemini) mobile "Launch Settings on iPhone 15 Pro Max" mobile "Open Instagram and like the first post" mobile "Calculate 15 + 25 in Calculator app" mobile "Launch Safari and go to google.com"

Single prompts with Claude

mobile --claude "Open Notes and create a new note" mobile --claude "Launch Camera and take a photo"

Interactive modes

mobile -i # Interactive with Gemini mobile --claude -i # Interactive with Claude mobile --interactive # Interactive with Gemini

Help

mobile -h mobile --help

Benefits

✅ No PATH modifications needed
✅ Self-contained in your project directory
✅ Works from any directory once loaded
✅ Easy to modify and customize
✅ No external files created
✅ Portable - just copy the script

Quick Workflow

1. One-time setup:

   chmod +x mobile-setup.sh
   source mobile-setup.sh
   

2. Daily usage:

   mobile "Launch Settings"
   mobile "Open Instagram"
   mobile -i  # for interactive mode
   

3. For permanent access (optional):

   echo "source $(pwd)/mobile-setup.sh" >> ~/.bashrc
   # Then restart terminal or run: source ~/.bashrc
   

---

Troubleshooting

Common Issues

1. "No active session" errors

   • Ensure Appium server is running on localhost:4723
   • Check device/simulator availability
   • Verify platform-specific setup (Xcode for iOS, Android SDK for Android)

2. Element not found errors

   • Use appium_get_page_source to inspect available elements
   • Try different locator strategies (id, xpath, accessibility_id)
   • Ensure proper timing - elements may need time to load

3. Python environment issues

   • The package automatically creates a virtual environment
   • If issues persist, check Python 3.8+ installation
   • Verify internet connectivity for dependency installation

Debug Mode

Set DEBUG=1 environment variable for verbose logging:

DEBUG=1 npx appium-mcp-server

Development

To modify or contribute to this package:

git clone https://github.com/yourusername/appium-mcp-server.git
cd appium-mcp-server
npm install
npm link  # for local testing

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please read the contributing guidelines and submit pull requests to the main repository.