Mobile MCP: let AI agents drive your iOS and Android apps. MCP server for simulators, emulators and real devices. Works with Claude Code, Codex, Cursor and any MCP client.
TypeScript agentandroidandroid-automationappium-alternativeclaude-codecodexcursoremulatoriosios-automationmcpmcp-servermobilemobile-automationmobile-testingreal-devicesimulatorskills
#!/usr/bin/env node
import { createMcpExpressApp } from "@modelcontextprotocol/express";
import { toNodeHandler } from "@modelcontextprotocol/node";
import { createMcpHandler } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { createMcpServer, getAgentVersion, getSdkVersion } from "./server";
import { error } from "./logger";
import { Request, Response } from "express";
import { program } from "commander";
type InstallOptions = { yes?: boolean };
const logMcpError = (err: Error) => {
error("Error handling MCP request: " + (err.stack ?? String(err)));
};
const startHttpServer = async (host: string, port: number) => {
// createMcpExpressApp applies express.json() and Host-header DNS rebinding
// protection automatically when binding to localhost / 127.0.0.1 / ::1.
const app = createMcpExpressApp({ host });
// Migration hint for clients still pointing at the removed SSE transport.
// Registered before auth so unauthenticated clients see the reason, not a 401.
app.all("/sse", (_req: Request, res: Response) => {
res.status(410).json({
jsonrpc: "2.0",
error: {
code: -32000,
message: "SSE transport removed. mobile-mcp now serves MCP Streamable HTTP at /mcp. See https://github.com/mobile-next/mobile-mcp#streamable-http-server-mode",
},
id: null,
});
});
const authToken = process.env.MOBILEMCP_AUTH;
if (!authToken) {
error("WARNING: MOBILEMCP_AUTH is not set. The HTTP server will accept unauthenticated connections. Set MOBILEMCP_AUTH to require Bearer token authentication.");
}
if (authToken) {
app.use((req, res, next) => {
if (req.headers.authorization !== `Bearer ${authToken}`) {
res.status(401).json({ error: "Unauthorized" });
return;
}
next();
});
}
// createMcpHandler serves both protocol eras from one factory: requests
// carrying the per-request `_meta` envelope (revision 2026-07-28, answered
// with `server/discover` and the modern result vocabulary) get a fresh
// era-marked instance, and legacy `initialize` traffic is served stateless
// from the same factory — the same per-request model as before.
// onerror keeps request-handling and transport failures in the application
// log (the SDK otherwise answers HTTP 500 silently).
const handler = createMcpHandler(() => createMcpServer(), { onerror: logMcpError });
const node = toNodeHandler(handler, { onerror: logMcpError });
app.post("/mcp", (req: Request, res: Response) => {
void node(req, res, req.body);
});
// Stateless mode has no long-lived sessions; GET (SSE stream) and DELETE
// (session teardown) are not applicable. Return 405 per SDK guidance.
const methodNotAllowed = (_req: Request, res: Response) => {
res.status(405).json({
jsonrpc: "2.0",
error: {
code: -32000,
message: "Method not allowed.",
},
id: null,
});
};
app.get("/mcp", methodNotAllowed);
app.delete("/mcp", methodNotAllowed);
app.listen(port, host, () => {
error(`mobile-mcp ${getAgentVersion()} streamable http server listening on http://${host}:${port}/mcp`);
});
};
const startStdioServer = async () => {
try {
// serveStdio owns the transport and the era decision for the
// connection: a `server/discover` probe (revision 2026-07-28) pins
// the connection modern, while an `initialize` handshake keeps
// serving the 2025-era protocol exactly as before. The factory runs
// lazily on the first message, so a failing createMcpServer() surfaces
// through onerror rather than the catch below.
serveStdio(() => createMcpServer(), { onerror: logMcpError });
// Exit cleanly on termination signals so node flushes pending work
// (including NODE_V8_COVERAGE output). Node's default SIGINT/SIGTERM
// handling terminates the process without writing the coverage file,
// which makes the `test:mcp` report come back all zeros.
const shutdown = () => {
process.exit(0);
};
process.on("SIGINT", shutdown);
process.on("SIGTERM", shutdown);
error(`mobile-mcp ${getAgentVersion()} (mcp sdk ${getSdkVersion()}) server running on stdio`);
} catch (err: any) {
console.error("Fatal error in main():", err);
error("Fatal error in main(): " + JSON.stringify(err.stack));
process.exit(1);
}
};
const installIntoDetectedClients = async (options: InstallOptions) => {
// add-mcp is ESM-only, loaded lazily so a normal server start does not pay for it
const { agents, detectGlobalAgents, upsertServer } = await import("add-mcp");
const prompts = await import("@clack/prompts");
const config = { command: "npx", args: ["-y", "@mobilenext/mobile-mcp@latest"] };
const detected = await detectGlobalAgents();
if (detected.length === 0) {
console.log("No MCP clients detected. See https://github.com/mobile-next/mobile-mcp#installation-and-configuration");
return;
}
// no terminal to draw checkboxes on (e.g. an agent ran us), so behave like --yes
let selected = detected;
if (!options.yes && process.stdin.isTTY) {
const answer = await prompts.multiselect({
message: "Install mobile-mcp into which clients?",
options: detected.map(agent => ({ value: agent, label: agents[agent].displayName })),
initialValues: detected,
required: false,
});
if (prompts.isCancel(answer)) {
prompts.cancel("Installation cancelled.");
return;
}
selected = answer;
}
for (const agent of selected) {
const result = upsertServer(agent, "mobile-mcp", config);
if (result.success) {
console.log(`✓ ${agents[agent].displayName}: ${result.path}`);
} else {
console.log(`✗ ${agents[agent].displayName}: ${result.error}`);
process.exitCode = 1;
}
}
};
const startServer = async () => {
const options = program.opts();
if (options.listen) {
const listen = (options.listen as string).trim();
const lastColon = listen.lastIndexOf(":");
let host = "localhost";
let rawPort: string;
if (lastColon > 0) {
host = listen.substring(0, lastColon);
rawPort = listen.substring(lastColon + 1);
} else {
rawPort = listen;
}
const port = Number.parseInt(rawPort, 10);
if (!host || !rawPort || !Number.isInteger(port) || port < 1 || port > 65535) {
error(`Invalid --listen value "${listen}". Expected [host:]port with port 1-65535.`);
process.exit(1);
}
await startHttpServer(host, port);
} else {
await startStdioServer();
}
};
const main = async () => {
program
.version(getAgentVersion())
.option("--listen <listen>", "Start Streamable HTTP server on [host:]port")
.option("--stdio", "Start stdio server (default)")
.action(startServer);
program
.command("install")
.description("Add mobile-mcp to the MCP clients detected on this machine")
.option("-y, --yes", "Install into every detected client without asking")
.action(installIntoDetectedClients);
await program.parseAsync(process.argv);
};
main().then();