Allows an AI agent to control a real Android phone, performing actions such as tapping, typing, swiping, long-pressing, scrolling, opening apps, pressing keys, toggling settings, reading system services, and taking screenshots.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@jevdevice tap the search button on my phone"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
jevdevice is an MCP server that lets an LLM agent control a real Android phone. It uses Jev, TypeSafe's System One decision model, to pick a real, runtime-discovered target for each action. The agent gives a goal in plain language, such as "tap the search button". Jev never sees a fixed list of buttons written in advance. It sees the real accessibility tree from the phone at that moment and picks from it.
Most phone-automation tools work from a hardcoded map. A script author writes down exact coordinates, resource IDs, or a fixed decision tree for each app. This breaks the moment an app updates its layout. It also does not generalize to an app the author never tested.
jevdevice does not hardcode any of that. Every action follows the same real pipeline:
Enumerate the real, current state (the on-screen accessibility tree, the installed app list, or a live dumpsys service).
Narrow that real list to a candidate with Jev, a small model built for exactly this kind of closed-set judgment.
Gate the resulting command with a second Jev check and a deny-list, before anything runs.
Run the command and, when asked, verify the result against the goal with another Jev check.
No step in this pipeline can select an option that does not exist on the real device at that moment. This makes the agent's action set correct by construction, not by a list someone kept up to date by hand.
Related MCP server: MCP Android Agent
The server exposes three tools over MCP:
device_do(goal, ...): runs exactly one real action for one goal. Jev first picks the kind of action the goal needs. The choices are: tap, type, swipe, long-press, scroll-to-find, press a key, open an app, toggle a radio, set Do Not Disturb, and read a system service. device_do then runs that one action and never chains a second one on its own. An LLM agent that wants a multi-step task still plans and sequences each device_do call itself.
device_screenshot(): returns a real screenshot of the current screen.
device_approve(thread_id, decision): resolves a pending action that needed a decision.
Every command that changes device state passes a gate before it runs. The gate rejects a fixed list of dangerous command shapes outright, for example rm, reboot, or a factory wipe. It asks Jev a direct safety question about every other command. A command Jev is unsure about returns needs_approval with a thread_id instead of running. A caller then either approves it through device_approve or passes auto_approve=True up front. A rejected command never runs, no matter which mode the caller used.
The codebase splits along this pipeline:
File | Role |
| Runs real |
| Parses the real accessibility tree into on-screen elements |
| Picks a tap, long-press, type, swipe, or scroll-to-find target and gates the result |
| Picks and gates system-service actions: toggle a radio, press a key, set Do Not Disturb, read |
| Picks a real installed app for a goal and verifies it opened |
| Picks which action kind a goal needs and dispatches to the matching propose/execute pair |
| The deny-list and the Jev safety check every mutating command passes |
| The MCP server itself, built on the modules above |
A naive read of the screen shells out to uiautomator dump, which starts a fresh Android runtime process each time. On a real device this costs about 2.2 seconds per call, most of it process startup, not the actual read. jevdevice instead sideloads uiautomator2's companion app once and keeps that connection open. A warm screen read then takes about 0.3 seconds.
You need:
Python 3.12 or later, and uv
adb, with an Android phone reachable over USB or wireless debugging
A TypeSafe API key (docs.typesafe.ai)
Steps:
Clone this repository and run uv sync.
Connect your phone and confirm it shows up: adb devices.
Set your device's serial as an environment variable: export ANDROID_SERIAL=<serial-from-adb-devices>.
Set your TypeSafe API key: export TYPESAFE_AI_API=<your-key>.
Add jevdevice-mcp to your MCP client's server config, or run uv run jevdevice-mcp directly to check it starts.
The first real screen read after startup installs uiautomator2's companion app on the phone automatically. This takes a few seconds once, and every read after that is fast.
uv run python -m jevdevice.dispatch "open the calculator" runs one goal from the command line and prints the result. A command that needs approval prompts you directly in the terminal.
uv run pytest runs the test suite. Most tests are pure unit tests with no device needed. tests/test_mcp_approval_flow.py is a live integration test and needs a real connected phone and a real API key.
Jev's safety check and the deny-list run before every mutating command, with no exception. auto_approve only changes what happens after Jev returns needs_approval for a command it is unsure about. A command the deny-list rejects, or that Jev rejects outright, never runs, regardless of auto_approve.
MIT. See LICENSE.
Resolve a pending action from any device_* tool. decision is "approve"
or "deny". An optional command overrides the proposed command (e.g. a
human-corrected variant), matching PLAN.md's device_approve(thread_id,
decision, command?) signature. include_screenshot=True attaches a real screenshot,
same off-by-default tradeoff as device_do.
| Name | Required | Description | Default |
|---|---|---|---|
| command | No | ||
| decision | Yes | ||
| thread_id | Yes | ||
| include_screenshot | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does solid work: it explains that 'decision' is approve or deny, that command can override the proposed command as a human-corrected variant, and that include_screenshot=True attaches a real screenshot with an off-by-default tradeoff. It does not describe post-approval effects or authorization requirements, but it discloses the core behavioral semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the essential behavioral content with no filler. The action is front-loaded, and each sentence earns its place: one for core resolution semantics, one for optional overrides and the screenshot tradeoff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description covers the main invocation concerns: what the tool does, what decisions are valid, how to override the command, and what include_screenshot does. It is slightly incomplete on what happens after approval or denial and does not describe the return value, but nothing critical prevents an agent from calling the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it largely does: it defines decision values, explains command's override role, and clarifies include_screenshot's effect and default. thread_id is only implied through the PLAN.md signature rather than semantically described, but the context of resolving a pending action makes its role reasonably clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Resolve a pending action from any device_* tool.' It clearly differentiates this from its siblings, device_do and device_screenshot, by positioning it as the approve/deny gate for pending actions rather than an executor or capture tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use when a pending action exists from any device_* tool and states the decision values and optional command override. It references device_do's tradeoff, giving a useful contextual anchor, though it does not explicitly state when not to use this tool or name direct alternatives for exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One tool for any single real phone action. Jev first picks which ONE atomic kind this goal wants -- open an app, tap, long-press, type, swipe, scroll-to-find, press a key, toggle a service, set DND, take a screenshot, or read a system service (the same ACTION_KINDS the CLI toolkit uses) -- then runs exactly that one real action and returns its result. include_screenshot=True also attaches a real screenshot of the resulting screen -- off by default since an image costs real context; ask for one at a checkpoint, not after every single step in a sequence. Never plans or chains more than one action; sequencing multiple goals is still the calling agent's job.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | ||
| verify | No | ||
| direction | No | down | |
| auto_approve | No | ||
| max_attempts | No | ||
| include_screenshot | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the transparency burden. It honestly discloses that exactly one action is run, results are returned, screenshots are off by default due to context cost, and chaining is not performed by the tool. However, it does not disclose side-effect potential for mutating actions, what verification or auto_approval do, or what happens on failure or retry, leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably sized and front-loaded with the tool's core purpose, and the screenshot guidance is practical. But it contains redundancy ('one tool for any single... action' vs 'Never plans or chains more than one action') and a confusing 'Jev first picks' narrative that could be stated more directly and compactly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schemahol, no annotations, and six parameters, the description is incomplete. It covers core single-action behavior and screenshot usage, but omits the return format, semantics of four parameters, failure/retry behavior, and any relation to sibling tools. An agent would likely need additional information or experimentation to invoke it correctly in all cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for all six parameters. It adds meaning for goal (an atomic action from the enumerated list) and include_screenshot (attaches screenshot, off by default, expensive), but verify, direction, auto_approve, and max_attempts remain entirely unexplained in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool executes one real phone action at a time and enumerates the supported atomic kinds (open app, tap, long-press, type, swipe, scroll-to-find, press key, toggle service, set DND, take screenshot, read system service). It is more specific than the generic name, but it does not directly distinguish itself from sibling tools device_screenshot and device_approve, especially since 'take a screenshot' is listed among its own action kinds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context: invoke one atomic action per call, never plan or chain, and request screenshots only at checkpoints because images cost context. However, it does not explicitly say when to prefer device_screenshot or device_approve, nor what conditions would make those siblings the better choice over this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a screenshot of the current screen and return the actual image -- never gated (read-only), no goal needed, no candidates to narrow.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly discloses read-only nature, no gating, no prerequisites, and that the actual image is returned. It could mention edge cases like unavailable screens, but the core behavioral profile is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single compact sentence front-loads the core action and return value, then uses short clauses to add gating and read-only context. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless screenshot tool with no output schema, the description covers what it does, its safety profile, and prerequisites. The only omission is output format or failure behavior, but 'actual image' sufficiently sets expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the description need not document args. It usefully reinforces that no goal or candidate narrowing is required, confirming the parameterless call is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: takes a screenshot of the current screen and returns the actual image. It also distinguishes itself from sibling tools by noting it is never gated, read-only, and needs no goal or candidate narrowing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly signals when it applies: whenever a current-screen image is needed, without a goal or candidate selection. The sibling contrast is implied but not named, and there is no explicit exclusion like 'use X instead'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0device_approvedevice_dodevice_screenshotScored across 3 tools
Each tool has a clearly distinct purpose: device_do executes atomic actions, device_screenshot captures the screen, and device_approve resolves pending approvals. No overlap or ambiguity between them, even though device_do covers many sub-actions internally.
All tools share the 'device_' prefix, creating a clear namespace. However, the verb part is inconsistent: 'do' is vague, 'screenshot' is a noun-as-verb, and 'approve' is a verb. The pattern is recognizable but not perfectly uniform.
Three tools is on the thin side for a device control server, but the design intentionally consolidates all atomic actions into device_do, making the count reasonable. Each tool has a distinct role and earns its place.
The surface covers core device interactions (actions, screenshots, approval resolution) without obvious dead ends. Minor gaps exist, such as no explicit listing of available action kinds or device status, but these are workable given the CLI-toolkit reference.
Control real Android and iOS devices with LLM agents — tap, swipe, type, automate flows.
Decision-assurance for AI agents: an auditable action boundary + receipt before it acts.
Human-in-the-loop approval for agent actions, with verifiable action-bound receipts.
Melaya is a remote MCP server. It gives an assistant hands on your own Android phone and browser: it reads the screen through the accessibility tree, then taps, types and navigates inside the apps and sites you allow-list, with no per-app API. It also builds, schedules and runs agent pipelines across 6k+ connected tools. OAuth 2.1, nothing to install.
