[!WARNING] The rewrite is still in preview. The Go relay and Android agent are usable for controlled testing, but the current Android rewrite has not completed the real-device stable-release gates. Read Release channels before treating it as production-ready.

[!CAUTION] GitHub releases v0.2.0 through v0.5.0 belong to the legacy Shizuku-based implementation. The rewrite uses the separate agent-v* release channel. The current signed preview is agent-v0.1.0.

What is rish-mcp?

rish-mcp exposes an Android device's own shell (uid 2000, equivalent to adb shell) as MCP tools for AI clients.

The Android agent opens an outbound-only WebSocket to a relay you control. AI clients connect to that relay through MCP over Streamable HTTP and authenticate with a bearer token. The device does not need to accept inbound Internet connections, so the setup works behind NAT/CGNAT.

                               outbound WebSocket
┌──────────────┐   MCP/HTTPS   ┌──────────────────────┐ ◀────────────────── ┌──────────────┐
│  AI client   │ ────────────▶ │   Go relay + MCP     │                     │ Android agent│
│ Claude, etc. │ ◀──────────── │  server/cmd/relay    │ ── shell command ─▶ │  adb shell   │
└──────────────┘                └──────────────────────┘ ◀── result/output ── └──────────────┘
                                         │
                                         │ version metadata / APK
                                         ▼
                               ┌──────────────────────┐
                               │ Public version server│
                               │ server/cmd/publicserver
                               └──────────────────────┘

The previous Node/TypeScript + Shizuku implementation is kept under before/ for reference. See plan.md for the rewrite rationale and docs/DESIGN.md for the architecture.

Highlights

• No root and no Shizuku — the Android app talks directly to the device's own adbd.
• MCP-native — exposes list_devices and run_shell through a remote Streamable HTTP MCP endpoint.
• Outbound-only agent connection — no inbound port needs to be opened on the phone.
• Self-hosted relay — keep shell-access credentials and command traffic on infrastructure you control.
• Go relay — compact deployment, straightforward concurrency, and a single server binary per target.
• Android Kotlin agent — wireless-debugging pairing on Android 11+, with an adb tcpip fallback for older devices.
• Separate public update service — release metadata/APK serving stays outside the shell-access trust boundary.

Project status

Quick start

1. Set up the relay

The easiest path is the npm setup utility. Docker is required for the server action.

# interactive setup
npx rish-mcp-setup

# or install/update the relay non-interactively
npx rish-mcp-setup --yes --action server

The installer creates or reuses AI_TOKEN and DEVICE_TOKEN, stores them under ~/.config/rish-mcp/relay.env, and runs the rish-mcp-relay container.

For reverse-proxy, Compose, and manual deployment options, see docs/USAGE.md.

2. Install and pair the Android agent

Use a signed agent-v* artifact from GitHub Releases and follow the release notes.

On Android 11+, enable Developer options → Wireless debugging → Pair device with pairing code, then enter the pairing information in the rish-mcp app. On older Android versions, use the documented PC-assisted adb tcpip flow.

Detailed pairing instructions are in docs/USAGE.md.

3. Connect an MCP client

Create a client configuration automatically:

npx rish-mcp-setup --yes --action client \
  --url https://mcp.example.com/mcp \
  --token "$AI_TOKEN"

Or configure a compatible MCP client manually:

{
  "mcpServers": {
    "phone": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <AI_TOKEN>"
      }
    }
  }
}

For Claude CLI, the equivalent setup is:

claude mcp add --transport http phone https://mcp.example.com/mcp \
  --header "Authorization: Bearer <AI_TOKEN>"

[!IMPORTANT] Put the bearer token in the Authorization header. Do not place access tokens in URLs or query strings.

MCP tools

list_devices()

Lists connected Android devices, including connection metadata such as agent version, connection age, and pending command count.

run_shell({ cmd, deviceId?, timeoutMs? })

Runs a command as Android shell uid (2000) and returns stdout, stderr, exit code, and timing information. deviceId is only required when more than one device is connected.

run_shell({ "cmd": "getprop ro.product.model" })

See docs/USAGE.md for the full tool contract.

Repository layout

app/                      Android Kotlin agent
server/cmd/relay/         MCP + WebSocket relay
server/cmd/publicserver/  Public version/APK server
cli/                      rish-mcp-setup npm package
docs/                     Design, usage, and release documentation
before/                   Legacy Shizuku + Node/TypeScript implementation

Build from source

Go servers

cd server
go build ./...
go test ./...

Server containers

docker build --target relay -t rishmcp-relay server
docker build --target publicserver -t rishmcp-public server

Android debug build

From the repository root:

docker build -t rishmcp-android-build -f app/Dockerfile.build app

docker run --rm -v "$PWD/app:/work" -w /work rishmcp-android-build \
  gradle --no-daemon testDebugUnitTest assembleDebug

Debug APK output:

app/app/build/outputs/apk/debug/app-debug.apk

Official signed builds are produced by the tag-driven Android release workflow using strict agent-vMAJOR.MINOR.PATCH tags.

Deployment

A Compose configuration for Traefik/Dokploy is included:

cp .env.example .env
# Edit MCP_HOST / PUBLIC_MCP_HOST and replace both secrets.
openssl rand -hex 32

docker network create dokploy-network  # once, if needed
docker compose up -d --build
curl -fsS "https://${MCP_HOST}/healthz"

The relay receives shell-access secrets and device traffic. The separate public server receives no relay token and only serves release metadata and the APK.

See docs/USAGE.md for environment variables, OAuth, reverse-proxy settings, and troubleshooting.

Security model

[!WARNING] AI_TOKEN effectively grants remote adb shell access to connected devices. Treat it like an SSH private key or other high-value credential.

• Commands run as shell uid 2000, not root.
• The Android agent initiates the connection to the relay; it does not expose an inbound shell service.
• Use HTTPS/WSS in real deployments.
• Keep AI_TOKEN and DEVICE_TOKEN secret and rotate them if they may have leaked.
• Scope is intentionally single-user / owner-operated, not a multi-tenant remote-device platform.

Please report vulnerabilities privately as described in SECURITY.md.

Release channels

Promotion requirements and signing details live in docs/RELEASES.md.

Documentation

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md before contributing.

License

rish-mcp is licensed under the MIT License.

[!WARNING] Legacy Shizuku release. This APK belongs to the retired pre-rewrite architecture. It is incompatible with the current no-Shizuku master code and Go relay. It is preserved only for existing legacy users; do not use it for a new installation.

---

What's Changed * add universal Wear OS support by @turin-dev in https://github.com/turin-dev/rish-mcp/pull/2 ## New Contributors * @turin-dev made their first contribution in https://github.com/turin-dev/rish-mcp/pull/2 Full Changelog: https://github.com/turin-dev/rish-mcp/compare/v0.3.0...v0.5.0