droid-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
droid-mcp
droid-mcp is an MCP server that lets an AI assistant drive Factory Droid on your machine. You connect an MCP client to it, and the assistant can start Droid sessions, run turns, answer permission prompts, manage long-running daemon sessions, and reach the hosted Factory API and the Context API through tools.
Getting Started
Paste this into your coding agent:
Read https://raw.githubusercontent.com/prathamdby/droid-mcp/main/SETUP.md and follow it to set up droid-mcp on this machine. Ask me the questions it lists first.Related MCP server: ARTEMIS MCP Server
What it does
The server provides 287 tools in seven families. 154 are generated from the Factory Droid SDK, one per wire method, and 133 are hand-written.
Prefix | Count | What the tools cover |
| 130 | Generated. The long-running |
| 24 | Generated. Session-scoped SDK methods, excluding session-owned and confirmed daemon-unserved methods. |
| 32 | The local turn loop, prompts, and per-session administration. |
| 81 | The hosted Factory API: computers, Environments, hosted sessions, wiki, CI, billing, organization, and service accounts. |
| 18 | The Context API on a Prem origin: spaces, documents, files, and stored session records. |
| 1 |
|
| 1 |
|
The 81 rest_* tools cover the 77 operations of the published Factory OpenAPI document (version 0.1.0), the two machine-template operations the SDK still calls, and the two /limits billing operations Droid CLI and the Factory App call.
Tool profiles
By default the server runs the compact profile. tools/list advertises 16 tools instead of 287, so a client spends about 23 KB of context on the list instead of about 340 KB:
The turn loop as first-class tools:
server_info,skill_read,session_create,session_stream,session_events,session_interrupt,session_close,session_list, and the three prompt answers.tools_searchfinds any of the 287 operations by keyword, family, or read-only hint, andtools_describereturns the full description and input schema of up to 20 of them.tool_callruns one operation by name with its arguments. It uses the same handler, validation, autonomy cap, and{ code, message }failures as the operation's own tool in the full profile.batchruns up to 20 operations in order in one call. An argument{ "$from": "<step id>", "path": "/json/pointer" }takes part of an earlier step's result, so intermediate results never return to the client.A result larger than
maxBytes(16 KB by default) returns a preview and aref.result_readreads the stored result by byte range or by JSON Pointer, so no data is lost. Refs expire 15 minutes after their last use and only the key that created a ref can read it.
If select fails after an operation completes, tool_call or the batch step returns invalid_select with a ref to its full result. Read that ref instead of repeating the operation. Byte offsets for result_read must fall on UTF-8 character boundaries; use nextOffset to page, or expect invalid_offset for an offset inside a character.
--tool-profile full advertises all 287 tools, one per operation. Every tool in both profiles carries MCP hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so a client can skip confirmation for reads and ask before destructive calls.
node --experimental-strip-types scripts/measure.ts prints the initialize and tools/list sizes for both profiles.
It also serves a droid skill and a droid prompt that teach the assistant the turn loop, so you do not have to explain it yourself.
A turn works like this.
session_createstarts a Droid child process for a working directory and an autonomy level. The server rejects any autonomy level above the cap reported byserver_info.session_streamsends the prompt and waits up towaitMs, 20 seconds by default and 300 seconds at most.If the turn is still running, call
session_eventswith the cursor it returned. The cursor is the next sequence number, one past the last event, so pass it back unchanged and events do not repeat. Call it until the status iscompleted,failed, orinterrupted. Arunningresult keeps the session; close it when you are done.session_runcloses the session itself unless it returnsrunning, in which case poll, answer prompts, and thensession_close.While the turn runs, prompts such as
pending_permission,pending_question, andpending_optionsappear, each with a deadline. Answer them with the matching tool.session_closestops the process. Sessions idle for 30 minutes are closed automatically.
Requirements
Node.js 24 or newer. The server runs its TypeScript directly with Node's type stripping, so there is no build step.
The
droidCLI on yourPATH.A Factory API key in
FACTORY_API_KEY. Droid itself needs this key, and so do therest_*andcontext_*tools.pnpm, to install dependencies.
Droid compatibility
Release surface checked on 2026-11-13: Droid CLI 1.9.0
and Droid SDK 0.10.0 are current.
The SDK still declares 165 wire methods and protocol 1.269.0; the 287-operation
inventory excludes four confirmed daemon-unserved droid.* reads.
CLI versions and wire protocol versions are separate.
The daemon client adopts the peer's protocol version and retries once on a mismatch.
droid_list_skills, droid_list_tools, droid_list_mcp_tools, and
droid_list_mcp_registry are not advertised. tool_call and batch return unknown_tool
with supported replacements: session_list_skills or daemon_list_skills,
session_list_tools, session_list_mcp_tools or daemon_list_mcp_tools, and
daemon_list_mcp_registry, respectively. These replacements require a session id.
tools_describe lists removed names in unknown without discarding valid descriptions.
Other methods rejected as unimplemented return daemon_method_unsupported with
the method and peer protocol version. Transport failures retain their codes;
malformed replies and schema failures remain daemon_protocol_error.
See the Factory changelog.
Set it up
pnpm install
export DROID_MCP_KEYS="$(openssl rand -hex 32)"
export FACTORY_API_KEY="fk-..."
pnpm startThe server listens on http://127.0.0.1:7337/mcp. Startup fails unless you set at least one MCP key. Generate a key with openssl rand -hex 32 and keep it secret. Only requests that carry the key reach a tool.
Connect a client
Add this to your MCP client's configuration:
{
"mcpServers": {
"droid": {
"type": "http",
"url": "http://127.0.0.1:7337/mcp",
"headers": { "Authorization": "Bearer <the key you generated>" }
}
}
}Then ask the client to read the droid prompt or the skill at skill://droid/SKILL.md, and call server_info first. It reports the version, the tool profile, the advertised tool count, the operation count, the autonomy cap, and the daemon connection.
If you run the server on another machine, put a TLS proxy in front of it and keep the key required. docs/hosting.md has a systemd unit, a keys file layout, and TLS setup for that case.
Configuration
Each flag also has an environment variable. The defaults work for a local install.
Flag | Environment | Default |
|
|
|
|
|
|
|
| none, startup fails without a key |
|
|
|
|
|
|
|
|
|
|
|
|
|
| none, the server spawns a daemon |
|
| |
|
| none, requests with an |
|
|
|
| none, the | |
| none | |
|
|
|
|
| |
|
| |
|
|
|
--max-autonomy accepts off, low, medium, or high. FACTORY_API_KEY is read from the environment and is never logged and never returned by a tool.
The skill gate covers all session_* tools and the daemon/hosted work-starting
operations listed in tool families.
Call skill_read, read exactly skill://droid/SKILL.md, get that URI through
skills/get, or get prompt droid to unlock them. Reference-only reads do not
count. The state is per MCP session; sessionless (2026-07-28) clients share it
per bearer key, not per client. Disable with --require-skill=false or
DROID_MCP_REQUIRE_SKILL=false.
FACTORY_BASE_URL and FACTORY_CONTEXT_BASE_URL must be bare http or https origins, with no path, query, fragment, or credentials. The rest_* tools call FACTORY_BASE_URL. The context_* tools call FACTORY_CONTEXT_BASE_URL, the Prem origin that serves the Context API, and fail with context_base_url_missing while it is unset. FACTORY_CONTEXT_HEADERS is a JSON object of string values sent with every Context request, for example {"x-factory-organization":"org-..."}. It may not set authorization, cookie, host, or framing headers such as content-type. An invalid value for any of the three stops startup with exit code 2. Context header values are treated as secrets, like the API key.
Security
Keep the MCP keys secret. Anyone who has a key can drive Droid on the host.
The server binds to localhost by default. Do not expose the port without TLS and a required key.
Requests that carry an
Originheader are rejected unless you allow that origin explicitly.The REST and Context tools redact secrets from results and errors. A minted service-account key value is never returned, and secret values sent to the organization secrets tool are never echoed back.
--max-autonomybounds localsession_createandsession_run, the permission outcomes those sessions offer, and any authority field a generated tool sends explicitly (autonomyLevel,autonomyMode,subagentAutonomyLevel, andskipPermissionsUnsafe: true).daemon_initialize_sessionanddroid_initialize_sessioncopy an omittedautonomyLevelorautonomyModefrom onedaemon_get_default_settingssnapshot onto that request. A snapshot value inside the cap is kept. A snapshot value above the cap is sent as the cap. A missing level is sent asoff, and a missing mode asnormal. When the cap is belowhigh, an omittedskipPermissionsUnsafeis sent asfalse. The snapshot is read for that request only; persistent defaults are left unchanged. Initialize has nosubagentAutonomyLevelfield.daemon_load_sessionanddroid_load_sessionsend no saved authority, and work already queued on that session can be running. Usesession_createandsession_runwhen the cap has to bound the work.daemon_initialize_sessioncopies an omittedautonomyLevel,autonomyMode, and, when--max-autonomyis belowhigh,skipPermissionsUnsafefrom onedaemon_get_default_settingssnapshot onto that request. A lower observed default is kept. A missing field becomesoff,normal, orfalse. The call does not change persistent defaults.daemon_load_sessionanddroid_load_sessionopen a saved session at the authority stored with it. List and message reads do not show that authority, anddaemon_initialize_sessionhas nosubagentAutonomyLevelfield. Use localsession_createorsession_runwhen the work must stay inside--max-autonomy.
Development
Command | What it does |
| Serve the MCP endpoint on |
| Connect to the daemon, authenticate, and print one JSON object |
| Run |
| oxlint, with the anti-slop plugin in |
| Check formatting with oxfmt |
| Run every test project that needs no model |
| Regenerate |
| Fail if a generated file is stale |
Tests split by what they need. The unit, http, process, and integration projects run against fakes and a real server process. The live project needs a real model and a real daemon and stays off by default.
Codegen uses TypeScript 6's compiler API. TypeScript 7 replaces that API and is
not a drop-in upgrade. Node type definitions stay on the Node 24 runtime baseline.
Optional tool inputs must be omitted when unused; null is accepted only where
the schema explicitly allows it, such as clearing an Environment's setup script.
The source layout:
src/
├── main.ts # doctor | serve
├── config.ts # flags and env, no Effect
├── http/ # Streamable HTTP and bearer auth
├── droid/ # exec client, turn hub, prompts, daemon, REST and Context
├── tools/ # hand-written tools plus one generated tool per SDK method
├── generated/ # codegen output, do not edit
└── skill/droid/ # the skill markdown, embedded at build timeLicense
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Remote MCP server for AI.TV creators — delegate account operations to your AI agent over MCP.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI agents and test runners to control Android devices via local ADB, including listing devices, tapping, swiping, typing, sending system keys, launching apps, and dumping UI hierarchy. Communicates over MCP stdio without exposing network listeners.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants and test suites to drive real Android devices or emulators through MCP, executing natural-language automation and testing workflows while collecting screenshots, Logcat output, and device state.Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables MCP-compatible AI assistants to see and control Android devices through screenshots, taps, swipes, typing, app management, UI inspection, file transfer, shell commands, and audio/video streaming. It connects over ADB with optional low-latency acceleration for faster input and near-instant screenshots.392 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables MCP-compatible AI assistants to see and control Android devices through ADB and a fast device-control protocol, including screenshots, touch input, typing, app management, UI inspection, file transfer, shell commands, and audio/video streaming.392 npmMIT