rish MCP server
Commit Nov 15, 2026Exposes an Android device's adb shell to AI clients through a secure, outbound-only WebSocket relay.
Also known as turin-dev/rish-mcp
- Stars
- 31
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is rish MCP?
rish exposes an Android device's adb shell to AI clients through a secure, outbound-only WebSocket relay.
Summary generated from the project's README
About rish MCP server
Giving AI assistants direct access to an Android device's shell is what rish-mcp enables through a secure, self-hosted architecture. This system allows developers to use tools like Claude to interact with a mobile device via adb shell commands without requiring root access or Shizuku. The setup uses an Android Kotlin agent that establishes an outbound-only WebSocket connection to a Go-based relay, making it compatible with devices behind NAT or CGNAT since no inbound ports need to be opened.
To use this, you deploy a relay server using Docker or the rish-mcp-setup npm utility and pair an Android device using wireless debugging on Android 11 or higher. AI clients connect to the relay via MCP over Streamable HTTP using a bearer token for authentication. The server provides specific tools including list_devices to view connected hardware and run_shell to execute commands as shell uid 2000, returning stdout and stderr directly to the client.
What you can do with it
- 1Execute shell commands remotelyAn AI client can run specific Android system commands and receive the output directly.
- 2Monitor connected Android hardwareDevelopers can ask an AI to check which devices are currently linked to the relay.
- 3Securely bridge mobile devices to AIUsers can provide AI access to a phone while keeping all command traffic on their own controlled infrastructure.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableturin-dev/rish-mcp is public and reachablegithub.com/turin-dev/rish-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/turin-dev/rish-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubrish-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.0throughv0.5.0belong to the legacy Shizuku-based implementation. The rewrite uses the separateagent-v*release channel. The current signed preview isagent-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_devicesandrun_shellthrough 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 tcpipfallback 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
Run the installer on a machine with Docker. It asks for the port, public URL and tokens, starts the relay, and can configure your MCP client (including claude mcp add) in the same run. Re-running it updates the relay.
curl -fsSL https://rish-mcp.turin.my | sh
To read the script before running it, open rish-mcp.turin.my/relay. For scripts, sh -s -- --yes asks nothing; see docs/USAGE.md for options. The npm utility also works: 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
Authorizationheader. 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_TOKENeffectively grants remoteadb shellaccess 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_TOKENandDEVICE_TOKENsecret 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.
rish MCP questions
Does this require root or Shizuku?
No, the Android app talks directly to the device's own adbd without needing root or Shizuku.
What tools are available via MCP?
The server provides list_devices to see connected devices and run_shell to execute commands as the Android shell uid 2000.