vaknin/mcp-android-ssh

Why Use This?

Turn your Android device into a programmable computer that AI can interact with naturally. Instead of manually SSH'ing into your phone every time you need to check something or run a command, just ask Claude:

• "Check if my Termux background service is running"
• "Download this paper to my tablet"
• "Find all PDFs on my device larger than 10MB"

Features

• Interactive setup tool - Configure through natural conversation with Claude
• Lightweight & fast - 401 KiB binary, memory-safe Rust implementation
• Smart safety - 81 whitelisted read-only commands run freely, writes require explicit tool
• Bulletproof connectivity - Auto-reconnect with retry logic, handles network drops
• Flexible auth - SSH key or password authentication
• Privacy-first - Local-only connection, no data leaves your network

Quick Start

# Install
cargo install mcp-android-ssh
claude mcp add --scope user --transport stdio mcp-android-ssh mcp-android-ssh

# Setup Termux (on Android)
pkg install openssh && sshd

# Copy your SSH key
ssh-copy-id -p 8022 -i ~/.ssh/id_ed25519.pub u0_a555@192.168.1.100

# Configure via Claude (recommended) - just ask:
"Set up Android at 192.168.1.100, user u0_a555, key ~/.ssh/id_ed25519"
# Then restart from /mcp menu

# Or manually edit: ~/.config/mcp-android-ssh/config.toml

cargo install mcp-android-ssh
claude mcp add --scope user --transport stdio mcp-android-ssh mcp-android-ssh

# Install and start SSH server
pkg update && pkg install openssh && sshd

# Find your username and IP address
whoami          # Example: u0_a555
ifconfig wlan0  # Example: 192.168.1.100

# Generate SSH key (skip if you already have one)
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""

# Copy key to Android (replace with your username and IP)
ssh-copy-id -p 8022 -i ~/.ssh/id_ed25519.pub u0_a555@192.168.1.100

"Set up my Android connection at 192.168.1.100, user u0_a555, use ~/.ssh/id_ed25519"

host = "192.168.1.100"        # Your Android device IP
port = 8022                    # SSH port (default 8022 for Termux)
user = "u0_a555"               # Your Termux username
key_path = "~/.ssh/id_ed25519" # Path to your SSH private key

# Optional: password authentication (not recommended)
# password = "your_password"

export ANDROID_SSH_HOST=192.168.1.100
export ANDROID_SSH_USER=u0_a555
export ANDROID_SSH_KEY_PATH=~/.ssh/id_ed25519

Usage Examples

File Management

• "Show me my most recent photos from /sdcard/DCIM"
• "Find all PDF files larger than 10MB"
• "What's taking up the most space on my phone?"

Development & Monitoring

• "Check if my PostgreSQL server is running"
• "Show me running processes sorted by memory"
• "Show me the last 50 lines of my server logs"

System Administration

• "Install python and pip on my device"
• "Create a backup of my Termux home directory"
• "Download this dataset to /sdcard"

Data Analysis

• "Find duplicate files in my photos"
• "Analyze my app usage with dumpsys"

API Reference

The server exposes three MCP tools that Claude can use:

execute_read - Safe Read-Only Commands

Executes whitelisted read-only commands without user approval. Perfect for browsing files, checking system status, and gathering information.

81 Whitelisted Commands Include:

• File operations: ls, cat, head, tail, grep, find, tree
• System monitoring: ps, top, df, du, free, uptime
• Network: ping, netstat, ss, ifconfig
• Text processing: wc, sort, cut, jq

Parameters:

• command (string, required) - The shell command to execute
• timeout (number, optional) - Timeout in seconds (default: 30, max: 300)

Example: ls -lah /sdcard/Download

execute - Full Command Access

Executes any command including write/modify/delete operations. Use this for installing packages, creating files, or modifying system state.

Parameters:

• command (string, required) - The shell command to execute
• timeout (number, optional) - Timeout in seconds (default: 30, max: 300)

Example: pkg install git

Note: Commands that aren't whitelisted in execute_read will automatically suggest using this tool instead.

setup - Interactive Configuration Helper

Configure your Android SSH connection directly through Claude. Supports partial updates and guides you through missing information.

Parameters (all optional):

• host (string) - Android device IP address
• port (number) - SSH port (default: 8022)
• user (string) - Termux username
• key_path (string) - Path to SSH private key
• password (string) - SSH password (not recommended)

Usage:

Complete setup in one go:

"Set up Android at 192.168.1.100, user u0_a555, key ~/.ssh/id_ed25519"

Or step-by-step - Claude will ask for missing info:

"Help me set up my Android connection"

Update just one field:

"Change the host to 192.168.1.101"

After setup completes, restart the MCP server from the /mcp menu.

Acknowledgments

• rmcp
• russh