zilbonn/android-mcp-emulator

Android Emulator MCP Server - Complete Implementation

This directory contains a complete, production-ready MCP server for Android emulator interaction.

📦 What You Have

A fully-functional MCP server with:

• ✅ 25+ tools for device control
• ✅ Complete documentation (7 docs)
• ✅ Helper scripts (cert installer, tester)
• ✅ Docker deployment ready
• ✅ Test suite included
• ✅ ~1500 lines of code
• ✅ Automated setup script - one command to set everything up!

🚀 Quick Setup

Automated Setup (Recommended)

Prerequisites:

• Python 3.10+ (brew install python@3.11 on macOS)
• ADB (brew install android-platform-tools on macOS)
• Android emulator running (start in Android Studio)

Setup in one command:

./setup.sh

The script will:

1. Check prerequisites (Python, ADB, emulator)
2. Create virtual environment
3. Install dependencies
4. Run tests
5. Configure Claude Desktop automatically
6. Create helper scripts (run_tests.sh, start_server.sh)

After setup completes, restart Claude Desktop and try:

"Take a screenshot of my Android emulator"

Manual Setup

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Test it works
python test_functionality.py

# Configure Claude Desktop manually
# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json
# Add MCP server configuration (see QUICKSTART.md)

# Start the server
python server.py

📚 Documentation Guide

🎯 What Can You Do?

Security Testing

• Setup mitmproxy or Burp Suite
• Intercept HTTPS traffic
• Install CA certificates
• Analyze API calls

Automated Testing

• Install and test APKs
• Navigate through apps
• Fill forms and login
• Screenshot verification

UI Exploration

• Capture all screens
• Map navigation flows
• Document UI elements
• Find accessibility issues

Development

• Test your apps
• Debug issues
• Automate workflows
• Integrate with CI/CD

🛠️ Key Files

Core Implementation

• server.py (850 lines) - The MCP server with all 25+ tools
• requirements.txt - Python dependencies
• setup.py - Package configuration

Helper Scripts

• cert_installer.py (260 lines) - Automate certificate installation
• test_functionality.py (400 lines) - Comprehensive test suite
• Makefile - Common commands

Deployment

• Dockerfile - Container image
• docker-compose.yml - Stack orchestration

Configuration

• claude_desktop_config.json - Template for Claude integration
• .gitignore - Git exclusions

⚡ Quick Commands

# Test everything works
python test_functionality.py

# Start the server
python server.py

# Install mitmproxy cert
python cert_installer.py ~/.mitmproxy/mitmproxy-ca-cert.pem

# Use Makefile shortcuts
make help           # See all commands
make test          # Run tests
make install-cert  # Install cert

🎓 Learning Path

Beginner (15 minutes)

1. Read PROJECT_SUMMARY.md
2. Run test_functionality.py
3. Try one example from EXAMPLES.md

Intermediate (1 hour)

1. Complete QUICKSTART.md
2. Configure Claude Desktop
3. Test 3-4 workflows
4. Setup proxy for an app

Advanced (Half day)

1. Read ARCHITECTURE.md
2. Study ADVANCED.md
3. Integrate with Frida/Burp
4. Build custom workflows

🔐 Security Warning

⚠️ This provides full device control!

Only use on:

• ✅ Test devices
• ✅ Development emulators
• ✅ Devices you own
• ✅ Local network

Never use on:

• ❌ Production devices
• ❌ Other people's devices
• ❌ Public networks
• ❌ Sensitive environments

📊 Project Stats

Files:          17 total
Documentation:  8 files (50KB)
Code:          3 files (60KB)
Scripts:       3 helpers
Config:        3 files

Lines of Code: ~1,500
Tools:         25+
Examples:      6+ workflows
Tests:         10 categories

🆘 Need Help?

Quick Troubleshooting

# Is ADB working?
adb devices

# Is emulator running?
adb shell ls

# Is Python setup correct?
python test_functionality.py

# Need more help?
open QUICKSTART.md  # Troubleshooting section

Common Issues

1. "No devices found" → Start emulator
2. "ADB not found" → Install Android SDK
3. "Tests failing" → Check QUICKSTART.md
4. "Device offline" → Restart emulator

💡 What's Next?

After getting started:

1. Try the examples - EXAMPLES.md has 6+ workflows
2. Read advanced docs - ADVANCED.md for power features
3. Integrate tools - Frida, Burp, OpenCV
4. Build workflows - Automate your testing
5. Contribute - Improve and extend!

🎉 You're Ready!

This is a complete, production-ready implementation. Everything you need is here:

• ✅ Full MCP server
• ✅ 25+ tools
• ✅ Complete documentation
• ✅ Helper scripts
• ✅ Test suite
• ✅ Example workflows
• ✅ Deployment configs

Start with QUICKSTART.md and you'll be running in 5 minutes!

For detailed navigation, see INDEX.md