You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* cap tool discovery at 45k characters ([#475](https://github.com/appium/appium-mcp/issues/475)) ([2624412](https://github.com/appium/appium-mcp/commit/2624412367e5a2e4cd5ababc15a9fb4c2ffc25c9))
***screenshot:** use resolveDriver for session rehydration parity ([#456](https://github.com/appium/appium-mcp/issues/456)) ([5bda643](https://github.com/appium/appium-mcp/commit/5bda643996bdba7116a2888e86991431cfa7ac60))
***command:** re-throw swallowed remote errors for element click, rect, and screenshot ([#457](https://github.com/appium/appium-mcp/issues/457)) ([940e07e](https://github.com/appium/appium-mcp/commit/940e07e6032b0673e9bb3aa44e25976ab3e69dcf))
* limit the node version to not use 26 ([#455](https://github.com/appium/appium-mcp/issues/455)) ([52b2d1a](https://github.com/appium/appium-mcp/commit/52b2d1a63fb8eccf6aed4991aba87ea28c156bec))
Copy file name to clipboardExpand all lines: README.md
+59-1Lines changed: 59 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,6 +12,7 @@ MCP Appium is an intelligent MCP (Model Context Protocol) server designed to emp
12
12
-[Prerequisites](#-prerequisites)
13
13
-[Installation](#️-installation)
14
14
-[Configuration](#️-configuration)
15
+
-[Remote server security and trust model](#remote-server-security-and-trust-model)
15
16
-[Available Tools](#-available-tools)
16
17
-[Plugin API](#-plugin-api)
17
18
-[Client Support](#-client-support)
@@ -149,9 +150,10 @@ This will automatically configure the MCP server for use with Claude Code. Make
149
150
|`CAPABILITIES_CONFIG`| Optional | Absolute path to a `capabilities.json` file with per-platform capability presets |
150
151
|`SCREENSHOTS_DIR`| Optional | Directory where screenshots and screen recordings are saved. Defaults to the current working directory |
151
152
|`NO_UI`| Optional | Set to `true` or `1` to disable HTML UI components — faster responses, fewer tokens. See [NO_UI Mode](#no_ui-mode)|
153
+
|`APPIUM_MCP_APPS_ENABLED`| Optional | MCP Apps static UI mode. Enabled by default. Set to `false` or `0` to force the embedded UI compatibility fallback. See [MCP Apps Mode](#mcp-apps-mode)|
152
154
|`APPIUM_MCP_ON_CLIENT_DISCONNECT`| Optional | Session cleanup when the MCP client disconnects: `delete_all` (default) deletes **MCP-owned** Appium sessions (`safeDeleteAllSessions`); `skip` keeps those sessions across disconnects (e.g. HTTP/stream clients that reconnect). Attached/remote sessions are not removed by this path. See [MCP disconnect behavior](#mcp-disconnect-behavior). |
153
155
|`APPIUM_MCP_WDA_APP_PATH`| Optional | Absolute path to a pre-extracted `WebDriverAgentRunner-Runner.app` bundle. When set, `prepare_ios_simulator` skips all GitHub downloads and uses this bundle directly — useful in environments where external downloads are blocked |
154
-
|`REMOTE_SERVER_URL_ALLOW_REGEX`| Optional | Regex pattern that remote Appium server URLs must match. Defaults to `^https?://`|
156
+
| REMOTE_SERVER_URL_ALLOW_REGEX| Optional | Regular expression applied to the complete remoteServerUrl value before MCP Appium connects to a remote Appium/WebDriver server. When unset, any HTTP(S) destination is accepted. Set this in shared infrastructure or CI environments that require an explicit destination policy. See Remote server security and trust model.|
155
157
|`AI_VISION_ENABLED`| Optional | Set to `true` to register the `appium_ai` tool (vision-based element finding). When unset or `false`, the AI tool is **not registered** and the LLM has no way to invoke vision-based finding. Requires `AI_VISION_API_BASE_URL` and `AI_VISION_API_KEY` to also be set, otherwise the server fails to start. |
156
158
|`AI_VISION_API_BASE_URL`| Required when `AI_VISION_ENABLED=true`| Base URL of the OpenAI-compatible vision model API |
157
159
|`AI_VISION_API_KEY`| Required when `AI_VISION_ENABLED=true`| API key for the vision model provider |
When enabled, appium-mcp creates spans for MCP tool calls, prompt loads, resource reads, and resource template reads. Error status is recorded for thrown operation errors and MCP tool results marked with `isError`. Span attributes intentionally avoid raw screenshots, XML page source, prompts, credentials, and other high-cardinality or sensitive payloads.
191
193
194
+
Tool spans include payload-free result-size attributes: `mcp.tool.result.content_count`, `content_types`, `text_chars`, `resource_count`, `resource_text_chars`, `image_count`, `audio_count`, `base64_chars`, and `base64_bytes_estimate` (all prefixed with `mcp.tool.result.`). `content_types` contains only known MCP types or `other`; payload values, resource URIs, MIME types, and unknown type strings are never recorded. Sizes are counted directly from known result fields without serializing or copying the complete result.
195
+
192
196
For local trace inspection, use the Jaeger setup in `tools/telemetry`:
193
197
194
198
```bash
@@ -326,6 +330,30 @@ More models benchmarked can be found [here](src/tests/benchmark_model/TEST_REPOR
326
330
327
331
### Performance Optimization
328
332
333
+
#### MCP Apps Mode
334
+
335
+
`appium_get_page_source` uses a static MCP App inspector by default when the client advertises MCP Apps support.
336
+
The XML remains in the normal text result for the LLM, while the inspector reads that same result instead of
337
+
receiving a duplicated XML copy.
338
+
339
+
For clients with unreliable MCP Apps rendering, set `APPIUM_MCP_APPS_ENABLED` to `false` or `0`:
340
+
341
+
```json
342
+
{
343
+
"appium-mcp": {
344
+
"env": {
345
+
"APPIUM_MCP_APPS_ENABLED": "false"
346
+
}
347
+
}
348
+
}
349
+
```
350
+
351
+
This keeps interactive UI enabled but forces the previous embedded page-source inspector. The compatibility mode
352
+
duplicates the XML inside the inspector HTML and therefore uses more result tokens and bandwidth. With a synthetic
353
+
95,000-character page source, the static mode reduced the result from approximately 267 KB to 95 KB (about 64%).
354
+
355
+
`NO_UI=true` or `NO_UI=1` takes precedence over this setting and disables both static and embedded UI.
356
+
329
357
#### NO_UI Mode
330
358
331
359
Set the `NO_UI` environment variable to `true` or `1` to disable UI components and improve performance:
@@ -419,6 +447,36 @@ HTTP and streamable MCP clients may **disconnect briefly** (reconnect, reload, p
419
447
420
448
**Tradeoff:**`skip` can leave **orphaned sessions** on your Appium server if nothing cleans up — use it when disconnect is not the same as “automation finished.”
421
449
450
+
### Remote server security and trust model
451
+
452
+
MCP Appium is designed to run as a local, single-user MCP server or as part of a trusted CI job. It is not intended to be exposed as a shared service to untrusted MCP clients.
453
+
454
+
The `remoteServerUrl` argument is intentionally configurable because MCP Appium acts as an Appium/WebDriver client and may need to connect to local, remote, private-network, or CI-hosted Appium servers.
455
+
456
+
Only allow trusted users and trusted workflow configuration to control `remoteServerUrl`. In particular:
457
+
458
+
* Do not expose the MCP tool surface directly to untrusted users.
459
+
* In CI, do not construct `remoteServerUrl` from untrusted pull request content, repository data, prompts, or other externally controlled input.
460
+
* Keep remote server URLs in trusted MCP or CI configuration where possible.
461
+
* Use `REMOTE_SERVER_URL_ALLOW_REGEX` to restrict the permitted Appium server URLs when the execution environment requires an explicit destination policy.
462
+
463
+
When `REMOTE_SERVER_URL_ALLOW_REGEX` is not set, MCP Appium accepts any syntactically valid HTTP or HTTPS destination. The variable is a regular-expression check against the complete `remoteServerUrl` value.
464
+
465
+
For example, to permit only a specific Appium server:
Treat this setting as an additional deployment safeguard. Network-level controls, CI isolation, and trusted MCP client configuration should remain the primary security boundaries.
478
+
479
+
422
480
## 🔌 Plugin API
423
481
424
482
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`.
0 commit comments