> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phones MCP tools

> The phone tools in the Appeeky MCP server, with their parameters and what each one returns.

The [Appeeky MCP server](https://docs.appeeky.com/docs/mcp.md) includes eleven phone tools. Any MCP client that is connected to Appeeky can use the phones on your Mac. There is nothing extra to install: connect the client once, then share your phones from Appeeky Desktop.

> [!NOTE]
>
> Phone tools use **0 API credits**. The MCP connection must use the same Appeeky account that is signed in to Appeeky Desktop.

***

## Tools

| Tool | Description |
| - | - |
| `phone_devices` | List connected phones with their ids, platform and screen size |
| `phone_observe` | Screenshot with numbered boxes over tappable elements, plus the element list |
| `phone_tap` | Tap an element or a point |
| `phone_long_press` | Press and hold an element or a point |
| `phone_swipe` | Drag from one element or point to another |
| `phone_scroll` | Scroll the screen |
| `phone_type` | Type into the focused text field |
| `phone_key` | Press a system key |
| `phone_open_app` | Launch an app |
| `phone_list_apps` | List installed apps |
| `phone_push_media` | Copy an image or video into the phone's gallery |

`phone_devices`, `phone_observe` and `phone_list_apps` are marked as read-only tools.

***

## How an assistant uses them

1. `phone_observe` returns the element list as text and the screenshot as an image.
2. The assistant picks an element by its number and acts, for example with `phone_tap`.
3. Every action returns a fresh observation, so the assistant rarely needs to call `phone_observe` twice in a row.

Element numbers expire after any action. The assistant must use the numbers from the most recent observation.

A tap on a button like Post, Send or Buy waits for you. The tool call stays open until you approve or deny on the **Phones** page of the dashboard, for up to 10 minutes. If you deny, the tool returns an error that starts with `APPROVAL_DENIED:` and the assistant should stop and ask you what to do. See [Approvals and safety](https://docs.appeeky.com/docs/phones/approvals-and-safety.md).

> [!WARNING]
>
> Some MCP clients stop waiting for a tool call after a while. If the call ends before you decide, the approval request is still open, and the tap runs when you approve it. Ask the assistant to observe the screen again to see the result.

***

## Common parameters

| Parameter | Type | Description |
| - | - | - |
| `device` | string | Device id from `phone_devices`. Optional when one phone is connected |
| `observe` | boolean | Return a fresh screenshot after the action. Default `true` |

Tools that take a target accept either `element`, or both `x` and `y`:

| Parameter | Type | Description |
| - | - | - |
| `element` | integer | Element number from the latest observation |
| `x`, `y` | number | A point in screenshot pixels, for places with no numbered element |

***

## phone\_devices

Lists the phones that are online. No parameters.

Returns the devices as JSON: `id`, `name`, `platform`, `driver`, `screen`, and `serial` when known. When no phone is online it returns `No phones connected.` with the setup problems your Mac reported.

## phone\_observe

| Parameter | Type | Default | Description |
| - | - | - | - |
| `device` | string | — | Device id |

Returns two parts: a text list of the elements, one per line as `[3] "Send" (button, clickable) at 512,1180`, and the screenshot as an image.

## phone\_tap

| Parameter | Type | Default | Description |
| - | - | - | - |
| `device` | string | — | Device id |
| `element` | integer | — | Element number |
| `x`, `y` | number | — | Point, when there is no element |
| `observe` | boolean | `true` | Return the new screen |

Returns the new observation, or `tap: done` with `observe: false`.

## phone\_long\_press

| Parameter | Type | Default | Description |
| - | - | - | - |
| `device` | string | — | Device id |
| `element` | integer | — | Element number |
| `x`, `y` | number | — | Point, when there is no element |
| `duration_ms` | integer | `800` | How long to hold, 100 to 10,000 |
| `observe` | boolean | `true` | Return the new screen |

## phone\_swipe

Drags from one place to another. For plain scrolling, use `phone_scroll`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `device` | string | — | Device id |
| `from` | object | required | `{ "element": 4 }` or `{ "x": 500, "y": 1000 }` |
| `to` | object | required | Same shape as `from` |
| `duration_ms` | integer | `300` | 50 to 5,000 |
| `observe` | boolean | `true` | Return the new screen |

## phone\_scroll

| Parameter | Type | Default | Description |
| - | - | - | - |
| `device` | string | — | Device id |
| `direction` | string | required | `up`, `down`, `left` or `right`. `down` shows the content below |
| `amount` | number | `0.5` | Fraction of the screen, 0.1 to 1 |
| `observe` | boolean | `true` | Return the new screen |

## phone\_type

Types into the focused text field. Tap the field first. Line breaks press Enter.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `device` | string | — | Device id |
| `text` | string | required | Text to type |
| `observe` | boolean | `true` | Return the new screen |

## phone\_key

| Parameter | Type | Default | Description |
| - | - | - | - |
| `device` | string | — | Device id |
| `key` | string | required | `home`, `back`, `enter`, `delete`, `app_switch`, `volume_up`, `volume_down` or `lock` |
| `observe` | boolean | `true` | Return the new screen |

Android supports all of them. iPhone supports `home`, `enter`, `delete`, `lock`, `volume_up` and `volume_down`.

## phone\_open\_app

| Parameter | Type | Default | Description |
| - | - | - | - |
| `device` | string | — | Device id |
| `app_id` | string | required | Package name on Android, bundle id on iPhone. See `phone_list_apps` |
| `observe` | boolean | `true` | Return the new screen |

## phone\_list\_apps

| Parameter | Type | Default | Description |
| - | - | - | - |
| `device` | string | — | Device id |

Returns the apps as JSON, each with `id` and `name`.

## phone\_push\_media

Copies an image or video into the phone's gallery so apps can pick it, for example when posting. Works on Android.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `device` | string | — | Device id |
| `url` | string | — | Link to the file. Your Mac downloads it first |
| `path` | string | — | Or: absolute path of a file on the Mac the phone is connected to |

Pass `url` or `path`. Returns `Copied to <path on the phone>. It is in the gallery now.`

***

## Errors

A failed tool call returns an error result with a text message. Policy errors start with a code:

| Starts with | Meaning |
| - | - |
| `APPROVAL_DENIED:` | You denied the tap, or the request expired |
| `APPROVAL_UNAVAILABLE:` | Approval could not be requested. Nothing was tapped |
| `RATE_LIMITED:` | The phone passed 30 actions per minute or 600 per hour |

Other messages describe the problem in plain words, for example `No phones are online.` See [Troubleshooting](https://docs.appeeky.com/docs/phones/troubleshooting.md).

***

## Example prompts

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
List my phones.
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Look at my phone and tell me what is on the screen.
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Copy my latest approved UGC clip to my Pixel and post it on TikTok with its caption.
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Open Instagram on my phone, go to my profile and read me the follower count.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.