Mobile FreeCode

mobile-freecode is an MCP server that lets any MCP client (Claude Code, Claude Desktop, the FreeCode desktop app, …) discover and control an Android phone running the FreeCode Agent app over your local network.

Direction of control: this server runs on your desktop and drives the phone. The phone is the device being controlled; the desktop is the controller. There is no reverse channel — the phone never drives the desktop.

The phone runs a lightweight WebSocket gateway (port 8765); this server finds it on the LAN, pairs with it once, and then routes tool calls to the phone's native capabilities (accessibility tree, taps / swipes / text, screenshots, and a live screen stream).

Tools

The full device-tool reference (every computer.* / screen.* / device.* / app.* tool, its parameters and return shape) is in docs/MOBILE_MCP_TOOLS.md.

Related MCP server: phone-control

Requirements

• Node.js ≥ 18.

• The FreeCode Agent app installed on the Android phone, its accessibility service enabled, notifications allowed, and the phone on the same Wi‑Fi as the computer running this server.

What this repo ships

This repository distributes the compiled connector (dist/) — the ready-to-run MCP server — not the TypeScript source. Clone it, install the two runtime dependencies, and run:

git clone https://github.com/zunairvf-sys/MCP-Mobile-FreeCode.git
cd MCP-Mobile-FreeCode
npm install          # pulls @modelcontextprotocol/sdk + ws
node dist/index.js   # speaks MCP over stdio

Wire it into an MCP client

Add an entry to your client's MCP config (here, .mcp.json):

{
  "mcpServers": {
    "mobile-freecode": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-Mobile-FreeCode/dist/index.js"]
    }
  }
}

Paired devices and this host's identity are stored per-user in ~/.freecode/ (mobile-paired.json, mobile-host.json) so every client that runs this server shares the same trust store.

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.

Trademarks

The Apache-2.0 license covers the code. It does not grant any right to the names or brand. "FreeCode", "FreeCode Agent", and "Mobile FreeCode", and their logos, are trademarks of the project author. You may fork and redistribute this code under the Apache-2.0 terms, but you may not:

• ship your fork under the "FreeCode" / "FreeCode Agent" name or logo,

• represent your build as the official FreeCode app, or

• reuse the FreeCode Agent Android package id or AdMob/publisher identifiers.

If you distribute a modified version, give it your own name.