Appium Moblile Automation MCP Server

Appium MCP春季启动服务器

A. Spring Boot 公开的应用程序 Appium移动自动化 能力作为 MCP（模型上下文协议）工具，使AI助手能够像 克劳德 直接控制Android设备。

运作原理

Claude Desktop → mcp-remote → Spring Boot MCP Server (port 8080) → Appium (port 4723) → Android Device

Claude可以在真实的Android设备上启动应用程序、与UI元素交互、截图和执行手势——所有这些都可以通过自然语言完成。

技术栈

项目结构

appium-mcp-springboot/
├── src/main/java/com/mcp/
│   ├── server/
│   │   └── Application.java          # Spring Boot entry point + Tool registration
│   ├── controller/
│   │   └── AppiumToolService.java    # MCP Tools exposed to Claude
│   └── driverManager/
│       └── DriverFactory.java        # Appium driver management
├── src/main/resources/
│   └── application.properties        # Server configuration
└── pom.xml                           # Maven dependencies

先决条件

• Java 17或更高版本
• Maven 3.6+
• Node.js（适用于Appium和mcp-remote）
• 安卓SDK和ADB
• 启用USB调试的Android设备
• 克劳德桌面版

安装和设置

1.克隆存储库

git clone 
cd appium-mcp-springboot

2.安装Appium和UiAutomator2驱动程序

npm install -g appium@latest
appium driver install uiautomator2

3.建设项目

mvn clean package

4.连接安卓设备

• 启用 开发人员选项 在您的Android设备上
• 启用 USB调试
• 通过USB连接并验证：

adb devices

您的设备UDID应出现在列表中。

5.获取应用程序详细信息

在设备上打开应用程序后，运行：

adb shell dumpsys window | grep mCurrentFocus

这给了你 appPackage 和 appActivity 需要启动应用程序。

运行服务器

启动Appium服务器

appium --relaxed-security

启动Spring Boot MCP服务器

选项A——来自Eclipse： 右击 Application.java → Run As → Java Application

选项B——从终端（不需要IDE）：

java -jar target/appium-mcp-springboot-1.0-SNAPSHOT.jar

服务器启动于 http://localhost:8080

Claude桌面配置

将此添加到您的 claude_desktop_config.json:

窗户： C:\Users\\AppData\Local\Packages\Claude_\LocalCache\Roaming\Claude\claude_desktop_config.json

雨衣： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "appium": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/sse"
      ]
    }
  }
}

保存配置后重新启动Claude Desktop。

可用的MCP工具

Claude中的示例用法

Launch the Android app with:
- platformVersion: 13
- deviceName: CPH2467
- udid: 97957054
- appPackage: com.example.app
- appActivity: com.example.app.MainActivity

添加新工具

要添加新工具，请添加一个方法 @Tool 注释在 AppiumToolService.java:

@Tool(description = "Click an element by its XPath")
public String clickElement(String xpath) {
    try {
        WebDriver d = DriverFactory.getDriver();
        if (d == null) return "Error: No active session. Launch app first.";
        d.findElement(By.xpath(xpath)).click();
        return "Clicked: " + xpath;
    } catch (Exception e) {
        return "Error: " + e.getMessage();
    }
}

然后重新启动Spring Boot服务器和Claude Desktop以获取新工具。

启动顺序（重要）

始终遵循以下顺序：

1. 启动应用程序： appium --relaxed-security
2. 启动Spring Boot服务器
3. 通过USB连接Android设备
4. 打开克劳德桌面

故障排除

No active session 错误

• 呼叫 launchAndroid 工具先于其他工具

Could not start a new session 错误

• 验证Appium是否正在运行： curl http://127.0.0.1:4723/status
• 验证设备是否已连接： adb devices
• 为端口添加防火墙规则 4723, 8200-8299, 7810

Claude未显示工具

• 验证端口上是否正在运行Spring Boot 8080
• 启动服务器后重新启动Claude Desktop

日志中的协议版本警告

• Client requested unsupported protocol version: 2025-11-25 --这只是一个警告，工具仍然正常工作

防火墙配置（Windows）

在管理命令提示符中运行：

netsh advfirewall firewall add rule name="Appium4723" dir=in action=allow protocol=TCP localport=4723
netsh advfirewall firewall add rule name="UiAutomator2" dir=in action=allow protocol=TCP localport=8200-8299
netsh advfirewall firewall add rule name="AppiumMjpeg" dir=in action=allow protocol=TCP localport=7810

许可证

该项目是开源的，可用于教育目的。