Android Forensics ADB MCP Server

A comprehensive Model Context Protocol (MCP) server for Android device forensic data acquisition using Android Debug Bridge (ADB). This tool is designed for forensic investigators with proper consent and authorization.

⚠️ Legal Notice

This tool is intended for authorized forensic investigations only. Users must have:

Legal authorization to access the device
Written consent from the device owner
Compliance with local laws and regulations
Proper chain of custody documentation

Unauthorized access to devices is illegal and unethical.

Features

Core Capabilities

Device Management: Connect and manage Android devices via ADB
Secure Command Execution: Whitelisted shell commands for safety
Full Device Backup: Create complete device backups (.ab format)
Backup Extraction: Convert Android Backup (.ab) to TAR format (Python port of adb-backup-extract)
Data Acquisition: Pull specific files and directories
Forensic Artifact Collection: Automated collection of common forensic artifacts
Metadata & Chain of Custody: Automatic forensic metadata generation

MCP Tools Available

check_adb_status: Verify ADB installation and availability
adb_devices: List all connected Android devices
adb_connect_device: Connect to specific device
adb_shell_command: Execute whitelisted shell commands
get_device_info: Get comprehensive device information
list_installed_packages: List all installed applications
adb_backup_device: Create full device backup
adb_pull_data: Pull files/folders from device
extract_backup_to_tar: Extract .ab backups to TAR format
collect_forensic_artifacts: Automated artifact collection

Prerequisites

Required Software

Python 3.13+: Required for the MCP server
Android Platform Tools: Install ADB
- Download: https://developer.android.com/tools/releases/platform-tools
- Add to system PATH
UV Package Manager: Already configured in your environment

Android Device Requirements

USB Debugging enabled (Settings → Developer Options → USB Debugging)
Device unlocked during data acquisition
USB cable connection or network ADB connection

Installation

Install Dependencies:

uv sync

Verify ADB Installation:

adb version

Test the Server:

uv run mcp dev main.py

Usage

Running the Server

Development Mode (with MCP Inspector)

uv run mcp dev main.py

Production Mode (Claude Desktop Integration)

uv run mcp install main.py --name "Android Forensics"

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "android-forensics": {
      "command": "uv",
      "args": [
        "--directory",
        "u:\\adb-connect",
        "run",
        "main.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Example Workflows

1. Basic Device Connection

1. Check ADB status: check_adb_status()
2. List devices: adb_devices()
3. Connect to device: adb_connect_device(device_id="DEVICE_SERIAL")
4. Get device info: get_device_info(device_id="DEVICE_SERIAL")

2. Full Device Backup

1. Create backup:
   adb_backup_device(
       output_file="evidence_backup.ab",
       device_id="DEVICE_SERIAL",
       include_apk=True,
       include_shared=True,
       all_apps=True
   )

2. Extract backup:
   extract_backup_to_tar(
       backup_file="evidence_backup.ab",
       output_tar="evidence_backup.tar",
       password="optional_password"
   )

3. Collect Forensic Artifacts

collect_forensic_artifacts(
    output_dir="./forensic_evidence",
    device_id="DEVICE_SERIAL"
)

4. Execute Shell Commands

adb_shell_command(
    command="pm list packages",
    device_id="DEVICE_SERIAL"
)

Security Features

Command Whitelisting

Only the following shell commands are allowed:

File operations: ls, cat, pwd, find, du, df
System info: getprop, dumpsys, uname, date, uptime
Package management: pm, am
Process management: ps, top
Network: netstat, ip, ifconfig
Logs: logcat
Settings: settings, content
Screen: screencap, wm

Validation

Commands are validated before execution
Shell operators (;, &&, ||, |) are checked
Timeout limits prevent hanging processes
Error handling for all operations

Backup Extraction Details

The extract_backup_to_tar tool is a Python implementation of the adb-backup-extract project.

Supported Features

✅ Unencrypted backups
✅ Encrypted backups (with password)
✅ Compressed backups (zlib)
✅ AES-256 decryption
✅ PBKDF2 key derivation

Backup File Format

Android backups (.ab) have the following structure:

ANDROID BACKUP\n
version\n
compressed (0 or 1)\n
encryption (none or AES-256)\n
[encryption metadata if encrypted]
[compressed/encrypted data]

Forensic Best Practices

Chain of Custody

All operations generate metadata including:

Timestamp (ISO 8601 format)
Device serial number
Operation performed
Investigator information
File hashes (where applicable)

Evidence Collection

Document Everything: Use get_device_info() first
Create Full Backup: Use adb_backup_device() for complete acquisition
Hash Evidence: Calculate SHA-256 hashes of all collected files
Maintain Logs: Keep all command outputs and errors
Write-Protect Evidence: Store backups as read-only immediately

Recommended Workflow

1. Connect device and verify connection
2. Document device information
3. Take screenshots of device state
4. Create full backup
5. Extract backup to TAR
6. Collect specific artifacts
7. Generate forensic report
8. Calculate and document all hashes
9. Store evidence securely

Troubleshooting

ADB Not Found

# Windows: Add to PATH or use full path
$env:PATH += ";C:\path\to\platform-tools"

# Verify
adb version

Device Not Detected

Enable USB Debugging on device
Accept RSA fingerprint on device
Try different USB cable/port
Check adb devices output

Backup Fails

Ensure device is unlocked
Confirm backup on device screen
Check available storage
Some apps may block backup

Permission Denied

Many forensic artifacts require root access
Use adb root if device is rooted
Consider using TWRP recovery for full access

Architecture

Project Structure

adb-connect/
├── main.py              # MCP server implementation
├── pyproject.toml       # Dependencies and configuration
├── README.md           # This file
└── .python-version     # Python version specification

Key Components

MCP Server: FastMCP-based server with tool registration
ADB Wrapper: Safe command execution with subprocess
Backup Extractor: Cryptography-based .ab to .tar converter
Forensic Collectors: Automated artifact acquisition
Metadata Generator: Chain of custody documentation

Dependencies

mcp[cli] >= 1.19.0: Model Context Protocol SDK
cryptography >= 43.0.0: Backup decryption (AES-256, PBKDF2)
pydantic >= 2.0.0: Data validation and serialization

Contributing

This is a forensic tool - contributions should prioritize:

Security and safety
Legal compliance
Evidence integrity
Documentation quality

References

License

MIT License - See LICENSE file for details.

Disclaimer

This tool is provided for legitimate forensic investigations only. The authors and contributors are not responsible for any misuse or illegal activities. Always ensure you have proper authorization before accessing any device.

For Forensic Investigation Departments: This tool is designed to support your authorized investigations with full respect for legal requirements and chain of custody procedures.

0x-Professor/DroidForensics-Suite