# Android Mobile MCP Server

Minimal Android-only fork of the original `mobile-mcp` project by MobileNext.

This project keeps only the Android functionality and exposes it through a Streamable HTTP MCP server protected by a shared bearer token.

## License and attribution

This project is derived from the original `mobile-mcp` project and is licensed under the Apache License 2.0.

Keep the Apache License file in this repository and preserve the original copyright notices. This repository is a modified Android-focused fork and is not the official upstream project.

## Requirements

- Node.js 20+
- Android SDK Platform Tools
- `adb` on your `PATH`
- one running Android emulator or one connected Android device
- a shared secret in `.env` via `MOBILEMCP_AUTH`

Check connectivity:

```bash
adb devices
```

## Setup environment

Create a `.env` file in the project root:

```env
MOBILEMCP_AUTH=your_shared_secret_here
```

You can use the example file:

```bash
cp .env.example .env
```

## Install and run

```bash
npm install
npm run build
node lib/index.js --listen 0.0.0.0:3000
```

Server URL:

```text
http://localhost:3000/mcp
```

The server requires a bearer token for every HTTP request.

## Auth header

```http
Authorization: Bearer your_shared_secret_here
```

## MCP config

```json
{
  "mcpServers": {
    "mobile-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your_shared_secret_here"
      }
    }
  }
}
```

## Example device-targeted tool call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "mobile_list_apps",
    "arguments": {
      "device": "emulator-5554"
    }
  }
}
```

Use the device ID from:

```bash
adb devices
```

## Docker

On Linux, expose the host ADB daemon on TCP port `5037` before starting the container:

```bash
adb kill-server
adb -a start-server
adb devices
```

The `-a` flag is required for Docker clients. Without it, ADB listens only on the host's local Unix socket and container commands fail with `Connection refused`.

The container must be told how to reach the host adb server. `host.docker.internal` is only available on Docker Desktop or when explicitly mapped for Linux.

### Docker Desktop / macOS / Windows

``` bash
docker build -t mobile-mcp-android .
```


### Linux with host networking

```bash
docker run -d \
  --network host \
  -e MOBILEMCP_AUTH=your_shared_secret_here \
  -e ADB_SERVER_SOCKET=tcp:127.0.0.1:5037 \
  --name mobile-mcp-android \
  mobile-mcp-android
```

If port 3000 is already in use, change the host port mapping to another port, for example `3000:3000` as above.

Then access the server at:

```text
http://localhost:3000/mcp
```

If you are debugging inside the container, the adb server should then resolve correctly:

```bash
docker exec -it mobile-mcp-android sh
adb devices
```

## Notes

- Android-only build
- iOS support removed
- intended for local Android automation and emulator/device control
- anyone without the correct `MOBILEMCP_AUTH` secret cannot connect

## License

This project is distributed under the Apache License 2.0.
See the included `LICENSE` file for the full text.