appium-mcp MCP工具

📋 Prerequisites

Before you begin, ensure you have the following installed:

System Requirements

• Node.js (v22 or higher)
• npm or yarn
• Java Development Kit (JDK) (8 or higher)
• Android SDK (for Android testing)
• Xcode (for iOS testing on macOS)

MCP Appium supports two driver modes:

• Embedded local drivers: when appium_session_management creates an android or ios session without remoteServerUrl, MCP Appium uses the bundled appium-uiautomator2-driver or appium-xcuitest-driver dependency directly. You still need the platform toolchains below, but you do not need to install a global Appium server or run appium driver install uiautomator2 / appium driver install xcuitest for this mode.
• Remote WebDriver/Appium server: when remoteServerUrl is provided to action=create or action=attach, MCP Appium uses the webdriver client to talk to that existing server. In this mode the remote server is responsible for its installed drivers, plugins, device access, and capability handling. Use this mode for platform=general; embedded local creation is available only for Android and iOS.

Mobile Testing Setup for embedded local drivers

Android

1. Install Android Studio and the Android SDK.
2. Set the ANDROID_HOME environment variable.
3. Add the Android SDK tools to your system's PATH.
4. Enable USB debugging on your Android device.
5. Install the Android platform tools/build tools and keep adb available on PATH.

iOS (macOS only)

1. Install Xcode from the App Store.
2. Install the Xcode Command Line Tools: xcode-select --install.
3. Install iOS simulators through Xcode.
4. For real device testing, enable Developer Mode on the device and sign in to your Apple ID in Xcode (Settings → Accounts). Use appium_prepare_ios_real_device to download and sign WebDriverAgent in a single call - it will guide you through provisioning profile selection and return capabilities for session startup.

🛠️ Installation

Standard config works in most of the tools::

{
  "mcpServers": {
    "appium-mcp": {
      "disabled": false,
      "timeout": 100,
      "type": "stdio",
      "command": "npx",
      "args": ["appium-mcp@latest"],
      "env": {
        "ANDROID_HOME": "/path/to/android/sdk",
        "CAPABILITIES_CONFIG": "/path/to/your/capabilities.json"
      }
    }
  }
}

Platform & Device Setup

Screenshots

Set the SCREENSHOTS_DIR environment variable to specify where screenshots are saved. If not set, screenshots are saved to the current working directory. Supports both absolute and relative paths (relative paths are resolved from the current working directory). The directory is created automatically if it doesn't exist.

⚙️ Configuration

Environment Variables

Note: For embedded local Android/iOS sessions, MCP Appium already includes the UiAutomator2 and XCUITest driver packages. The system-level requirements are the platform toolchains (ANDROID_HOME, Java, Android SDK tools, Xcode/iOS signing or simulator setup). For remote sessions, configure those requirements on the remote Appium/WebDriver server instead.

Optional: include sanitized non-sensitive argument values in spans.

Optional: attach custom key=value pairs to every span (e.g. test case ID, team name).

🔌 Plugin API

Use appium-mcp/core to compose the default Appium MCP server with custom business logic without maintaining a fork. Plugins can register MCP tools, prompts, resources, and resource templates, and can wrap tool execution with lifecycle hooks. Call hooks are tool-only: prompts, resources, and resource templates are registered with FastMCP but are not wrapped by beforeCall or afterCall.

createAppiumMcpServer({ policy }) can also hide nonmatching tools and resources from MCP discovery. The factory is async, so await it before starting the returned server. Policy rules are regular expressions matched against tool and resource names exactly as registered. The policy is applied at registration time to both single and batch registration methods. Resource policy matches the resource name only; resources or resource templates without a string name cannot match a non-empty allowResources list.

import { createAppiumMcpServer } from 'appium-mcp/core';
import type {
  AppiumMcpPlugin,
  McpRegistry,
  ToolCallContext,
} from 'appium-mcp/core';
import { z } from 'zod';

class CheckoutPlugin implements AppiumMcpPlugin {
  readonly name = 'checkout-plugin';
  readonly version = '1.0.0';

  register(registry: McpRegistry): void {
    const parameters = z.object({ orderId: z.string() });
    registry.addTool({
      name: 'assert_checkout_summary',
      description:
        'Assert that the checkout summary screen shows an expected order ID.',
      parameters,
      execute: async (args) => {
        const { orderId } = parameters.parse(args);
        return {
          content: [
            { type: 'text', text: `Assert checkout order ${orderId}` },
          ],
        };
      },
    });
  }

  async beforeCall(ctx: ToolCallContext): Promise<void> {
    if (ctx.toolName === 'appium_gesture') {
      console.error(`[checkout-plugin] about to call ${ctx.toolName}`);
    }
  }
}

const server = await createAppiumMcpServer({
  plugins: [new CheckoutPlugin()],
  additionalInstructions: 'Custom checkout policies are active.',
  policy: {
    allowTools: [/^appium_session_management$/, /^assert_checkout_summary$/],
    allowResources: [/^Generate Code With Locators$/],
  },
});

await server.start({ transportType: 'stdio' });

Plugin lifecycle:

• register(registry, core): called during server construction. Register custom tools, prompts, resources, and resource templates here.
• initialize(ctx): called lazily on the first MCP client connection. Use it for async setup such as artifact storage or internal service clients.
• beforeCall(ctx): called before a registered MCP tool executes. Return a ToolCallResult to short-circuit the tool. This hook only applies to tools, not prompts, resources, or resource templates.
• afterCall(ctx, result): called after a registered MCP tool executes. Return a modified ToolCallResult to decorate or replace the response. This hook only applies to tools, not prompts, resources, or resource templates.
• destroy(): called after the last MCP client disconnects.

Safe plugin surface

The supported plugin API is intentionally small:

McpRegistry methods delegate to the matching FastMCP registration APIs, so their object shapes follow FastMCP's documented tool, prompt, resource, and resource-template definitions. Appium MCP wraps registered tools with plugin call hooks, but prompts and resources are registered directly with FastMCP.

Each plugin name should be unique within the server. If two plugins use the same name, Appium MCP keeps the first plugin registered for that name and skips later plugins with a warning. Use a stable, package-style or organization-prefixed name, such as acme-checkout-plugin, to avoid collisions when composing plugins from multiple teams.

Each tool name should also be unique across all plugins and the core server. Tool names follow FastMCP behavior, not plugin-name behavior: when a tool is registered with the same name as an existing tool, FastMCP replaces the earlier tool definition with the later one. Appium MCP registers built-in tools before plugin tools, which means a plugin tool that uses the same name as a built-in tool replaces the built-in tool. Appium MCP tools usually have an appium_ prefix, so plugin tool names should use that pattern only when they intentionally override a core tool.

Verify plugin and tool names

Use verifyAppiumMcpNames before publishing or deploying a custom plugin setup. It registers your plugin capabilities into a lightweight collector, registers the Appium MCP core tools, and reports duplicate plugin names, duplicate tool names, and registration errors without starting the MCP server.

The recommended approach is to verify the same plugin array you pass to createAppiumMcpServer({ plugins }). This preserves your real plugin instances and order:

import {
  formatVerificationReport,
  verifyAppiumMcpNames,
} from 'appium-mcp/core';
import { plugins } from './plugins.js';

const report = verifyAppiumMcpNames({ plugins });

console.log(formatVerificationReport(report));
process.exit(report.ok ? 0 : 1);

When you provide multiple plugins, order is preserved. Plugins are verified in array order after the appium-mcp core tools. This matters because Appium MCP keeps the first plugin for a duplicate plugin name and skips later plugins with the same name, while duplicate tool names follow FastMCP's later-registration-wins behavior. Tool names still need to be unique across all loaded plugins and appium-mcp core; the verifier reports any collisions it finds.

The report labels this package's own shipped tools as appium-mcp core. Plugin sources are labeled as plugin:<name> with the plugin version.

Treat anything outside appium-mcp/core as internal. In particular, plugins should not rely on private server internals, internal session-store modules, tool implementation files, or the raw FastMCP server instance. If a plugin needs another stable primitive, open an issue so it can be added to AppiumMcpCore or McpRegistry deliberately.

See examples/plugin-example.ts for a fuller cookbook with tools, prompts, resources, resource templates, call hooks, and lifecycle setup.