rish-mcp

Give AI assistants secure, self-hosted MCP access to your Android device's adb shell — without root, Shizuku, or a permanently attached PC.

English · 한국어

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

Component	Status
Go relay (`server/cmd/relay`) — MCP, WebSocket relay, bearer auth + OAuth	✅ Built and tested
Public version server (`server/cmd/publicserver`)	✅ Built and tested
Android `AdbShellClient` — pairing and shell execution	✅ Built; unit-testable parts tested
Android UI/service — `MainActivity`, `AgentService`, `ConnectionManager`	🧪 Builds successfully; real-device validation still in progress
Signed rewrite APK	🧪 `agent-v0.1.0` preview available
Docker packaging / Compose deployment	✅ Available
Low-spec hybrid mode + FCM wake	⛔ Planned; requires Firebase configuration

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

Channel	Meaning
`agent-v*`	Current Android rewrite artifacts
`v0.2.0`–`v0.5.0`	Legacy Shizuku application; incompatible with the rewrite
npm `rish-mcp-setup`	Relay/client setup utility only; it does not install the Android APK

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

Documentation

Document	Contents
`docs/USAGE.md`	Deployment, pairing, MCP tools, OAuth, protocol details, troubleshooting
`docs/DESIGN.md`	Current architecture and implementation boundaries
`docs/RELEASES.md`	Release channels, signing, and promotion gates
`plan.md`	Rewrite rationale and project direction
`cli/README.md`	`rish-mcp-setup` CLI reference
`CONTRIBUTING.md`	Contribution guide

Contributing

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

License

rish-mcp is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
.github		.github
app		app
before		before
cli		cli
docs		docs
server		server
web		web
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
plan.md		plan.md

Navigation Menu

Repository files navigation

rish-mcp

What is rish-mcp?

Highlights

Project status

Quick start

1. Set up the relay

2. Install and pair the Android agent

3. Connect an MCP client

MCP tools

`list_devices()`

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

Repository layout

Build from source

Go servers

Server containers

Android debug build

Deployment

Security model

Release channels

Documentation

Contributing

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

rish-mcp

What is rish-mcp?

Highlights

Project status

Quick start

1. Set up the relay

2. Install and pair the Android agent

3. Connect an MCP client

MCP tools

list_devices()

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

Repository layout

Build from source

Go servers

Server containers

Android debug build

Deployment

Security model

Release channels

Documentation

Contributing

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`list_devices()`

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