Appium-MCP-服务器

Name: Appium-MCP-服务器
Author: argneshu

作者：argneshu6 星标更新：2025-09-28

安装使用来源：spider==github.com

项目介绍

Appium MCP 服务器

一个提供给 Claude 和其他兼容 MCP 客户端使用的 Appium 移动自动化能力的 Model Context Protocol (MCP) 服务器。

功能

跨平台移动自动化：支持 iOS 和 Android
多种应用启动模式：原生应用、浏览器自动化或已安装的应用
元素交互：查找、点击和向移动元素输入文本
会话管理：启动、监控和终止 Appium 会话
页面检查：获取页面源码和滚动功能
易于集成：与 Claude Desktop 和其他 MCP 客户端无缝集成

预备条件

Python 3.12+ 已安装在系统上：环境变量应在您的 bash 或 zsh 中正确设置，以便 claude 能够从系统中读取它
Node.js 18.1+ （用于 npx 使用）
Appium 服务器 在 http://localhost:4723 上运行
移动设备/模拟器 已配置并可访问

设置 Appium 服务器

# 全局安装 Appium
npm install -g appium

# 安装您的平台驱动
appium driver install xcuitest     # 对于 iOS
appium driver install uiautomator2 # 对于 Android

# 启动 Appium 服务器
appium server --port  4723

安装及使用

方案 1：使用 npx（推荐）

在您的 Claude Desktop 配置文件中添加以下配置：

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

⚙️ 系统设置说明（适用于 Apple M1/M2 和 Windows）

🍎 Apple Silicon (M1/M2) – macOS

Apple Silicon 用户必须本地重建 Python 虚拟环境（.venv）以避免架构兼容性错误，如：

ImportError: ... 不兼容的架构（有 'x86_64'，需要 'arm64'）

✅ 针对 M1/M2 Mac 的步骤：

🧬 克隆项目
📂 打开终端
导航到您的项目仓库
🛠️ 运行：chmod +x bootstrap.sh
🛠️ 运行：./bootstrap.sh
- 🧹 删除预构建的 .venv
- 🧱 使用本地 arm64 Python 重新创建 .venv
- 📦 重新安装所有 Python 依赖项
🔁 您只需执行一次，除非 .venv 被删除或 requirements.txt 发生变化

💻 Windows 用户

Windows 用户可以使用捆绑的 .venv（如果兼容），或者本地重新生成它。

✅ 针对 Windows 的步骤：

🧬 克隆项目
📂 打开命令提示符或 PowerShell
📁 导航到您的项目文件夹（例如 cd C:\Users\YourName\appium-mcp-server）
🛠️ 运行：bootstrap.bat
- 🧱 使用您系统的 Python（≥ 3.10）创建一个新的 .venv
- 📦 从 requirements.txt 安装所有依赖项
🛑 确保 Python 在您的 PATH 中且版本**≥ 3.10**

🧪 验证是否正常工作

🧪 启动服务器

在运行适当的设置脚本（macOS 上的 ./bootstrap.sh 或 Windows 上的 bootstrap.bat）之后，使用以下任一方式启动 MCP 服务器：

npx appium-mcp-server

或者直接从项目路径运行：

node bin/appium-mcp-server.js

您应该看到如下输出：
🚀 正在使用 python3.12 启动 MCP 服务器
🔧 注入 PYTHONPATH = ...

🧪 使用 Claude Desktop 与本地项目

要使用 Claude Desktop 运行您的本地版本MCP 服务器，请按照以下步骤操作：

打开 Claude Desktop
前往 设置 → 开发者 → 编辑配置按钮
这将打开 desktip-claude-config.json 文件
在 "mcpServers" 下添加以下配置：

🍎 macOS（Intel 或 Apple Silicon）

{
  "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"]
    }
  }
}

📝 将 `/Users/your.name/...` 替换为您克隆项目的完整路径。

可用工具

会话管理

appium_start_session：启动一个 Appium 会话
- platform： "iOS" 或 "Android"
- device_name：设备名称或 UDID
- app_path：应用文件路径（可选）
- bundle_id： iOS 包 ID（可选）
- app_package： Android 包名（可选）
- app_activity： Android 活动（可选）
appium_get_session_info：获取当前会话信息
appium_quit_session：终止当前会话

元素交互

appium_find_element：查找屏幕上的元素
- strategy： "id", "xpath", "class_name", 或 "accessibility_id"
- value：定位值
appium_tap_element：点击元素
- element_id：之前找到的元素 ID
appium_input_text：向输入字段发送文本
- element_id：目标元素 ID
- text：要输入的文本

页面导航

appium_get_page_source：获取当前页面源码
appium_scroll：滚动屏幕
- direction： "up" 或 "down"

示例使用方法（与 Claude 结合）

在 iPhone 15 Pro Max 模拟器上启动一个 iOS 会话，然后导航到 SauceDemo 网站并自动化登录过程。

Claude 将使用 MCP 服务器来：

启动一个 Appium 会话
查找登录元素
输入凭据
在应用中导航

配置示例

iOS Safari 浏览器测试

{
  "platform": "iOS",
  "device_name": "iPhone 15 Pro Max"
}

Android Chrome 浏览器测试

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

iOS 原生应用测试

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

Android 原生应用测试

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

🚀 快速开始指南（使用 Gemini CLI）

最简单的方法是使用我们的简单 CLI 包装器 Gemini 来运行移动自动化命令。

设置说明

🧬 克隆项目
📂 打开终端
导航到您的项目仓库
确保您已经在项目根目录下创建了 .env 文件，并在其中输入 GEMINI_API_KEY

加载来自 .env 的环境变量

load_dotenv()

获取 API 密钥

api_key = os.getenv("GEMINI_API_KEY")

使设置脚本可执行：
```
chmod +x mobile-setup.sh
```

加载移动函数：

source mobile-setup.sh

您应该看到：

移动自动化函数已加载！
使用：mobile "在 iPhone 上启动设置"
       mobile -i
       mobile --claude "打开 Instagram"

若要永久生效，请将此内容添加到您的 ~/.bashrc 或 ~/.zshrc：
source "/path/to/your/mobile-setup.sh"

测试函数：

# 测试帮助
mobile -h

# 测试交互模式
mobile -i

# 测试单个命令
mobile "在 iPhone 15 Pro Max 上启动设置"

# 测试与 Claude 结合
mobile --claude "打开 Instagram 并向下滚动"

使其永久可用（可选）

要在每次打开终端时都有 mobile 函数可用：

对于 Bash 用户：

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

对于 Zsh 用户：

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

对于 Fish shell 用户：

mkdir -p ~/.config/fish/functions
# 然后手动创建 fish 函数文件

使用示例

# 单个提示（默认 Gemini）
mobile "在 iPhone 15 Pro Max 上启动设置"
mobile "打开 Instagram 并点赞第一个帖子"
mobile "在计算器应用中计算 15 + 25"
mobile "启动 Safari 并前往 google.com"

# 单个提示与 Claude 结合
mobile --claude "打开笔记并创建新笔记"
mobile --claude "启动相机并拍照"

# 交互模式
mobile -i                    # 与 Gemini 交互
mobile --claude -i           # 与 Claude 交互
mobile --interactive         # 与 Gemini 交互

# 帮助
mobile -h
mobile --help

对于 Windows：

运行设置脚本： cmdmobile-setup.bat 您应该看到：移动自动化命令已创建！

使用：mobile "在 iPhone 上启动设置" mobile -i mobile --claude "打开 Instagram"

'mobile' 命令现在对本次会话可用。您应该看到：移动自动化函数已加载！使用：mobile "在 iPhone 上启动设置" mobile -i mobile --claude "打开 Instagram"

要永久生效，请将此内容添加到您的 ~/.bashrc 或 ~/.zshrc： source "/path/to/your/mobile-setup.sh"

测试函数： bash# 测试帮助 mobile -h

测试交互模式

mobile -i

测试单个命令

mobile "在 iPhone 上启动设置"

测试与 Claude 结合

mobile --claude "打开 Instagram 并向下滚动"

使其永久可用（可选）对于 Windows：命令提示符：

将脚本目录添加到系统 PATH，或每次打开新的命令提示符时运行 mobile-setup.bat

使用示例 bash# 单个提示（默认 Gemini） mobile "在 iPhone 15 Pro Max 上启动设置" mobile "打开 Instagram 并点赞第一个帖子" mobile "在计算器应用中计算 15 + 25" mobile "启动 Safari 并前往 google.com"

单个提示与 Claude 结合

mobile --claude "打开笔记并创建新笔记" mobile --claude "启动相机并拍照"

交互模式

mobile -i # 与 Gemini 交互 mobile --claude -i # 与 Claude 交互 mobile --interactive # 与 Gemini 交互

帮助

mobile -h mobile --help


### 优点

✅ **无需修改 PATH**  
✅ **项目目录内自包含**  
✅ **加载后可在任何目录使用**  
✅ **易于修改和定制**  
✅ **不创建外部文件**  
✅ **便携式 - 只需复制脚本**

### 快速工作流程

1. **一次性设置：**
   ```bash
   chmod +x mobile-setup.sh
   source mobile-setup.sh

日常使用：

mobile "启动设置"
mobile "打开 Instagram"
mobile -i  # 用于交互模式

永久访问（可选）：

echo "source $(pwd)/mobile-setup.sh" >> ~/.bashrc
# 然后重启终端或运行：source ~/.bashrc

故障排除

常见问题

"无活动会话" 错误
- 确保 Appium 服务器在 localhost:4723 上运行
- 检查设备/模拟器的可用性
- 验证特定平台的设置（iOS 使用 Xcode，Android 使用 Android SDK）
元素未找到错误
- 使用 appium_get_page_source 检查可用元素
- 尝试不同的定位策略（id, xpath, accessibility_id）
- 确保适当的时间 - 元素可能需要时间加载
Python 环境问题
- 该包自动创建虚拟环境
- 如果问题持续，请检查 Python 3.8+ 的安装
- 验证互联网连接以安装依赖项

调试模式

设置 DEBUG=1 环境变量以启用详细日志记录：

DEBUG=1 npx appium-mcp-server

开发

要修改或为此包贡献：

git clone https://github.com/yourusername/appium-mcp-server.git
cd appium-mcp-server
npm install
npm link  # 用于本地测试

许可证

MIT 许可证 - 详情见 LICENSE 文件。

贡献

欢迎贡献！请阅读贡献指南并向主仓库提交拉取请求。