Apktool MCP Server

A powerful Model Context Protocol (MCP) server that exposes Apktool functionality for Android APK analysis and reverse engineering. Integrates seamlessly with Gemini CLI to provide AI-powered APK security analysis, privacy auditing, and reverse engineering guidance through natural language commands.

🚀 Features

🔍 Comprehensive APK Analysis

Decompile APKs to extract resources, manifest, and smali code
Analyze permissions and app components for security assessment
Extract string resources and detect hardcoded secrets
Search smali code for specific patterns and security vulnerabilities
Recompile modified APKs after making changes

🤖 AI-Powered Workflows

Natural language commands for complex APK analysis tasks
Automated security audits with AI-generated insights
Privacy compliance checking and GDPR/CCPA analysis
Step-by-step reverse engineering guidance
Intelligent vulnerability detection and risk assessment

🛠 8 Core Tools

Tool	Description
`decode_apk`	Decompile APK files to extract all components
`build_apk`	Recompile APK from modified source directory
`install_framework`	Install system frameworks for system app analysis
`analyze_manifest`	Parse AndroidManifest.xml for permissions and components
`extract_strings`	Extract string resources with locale support
`list_permissions`	Enumerate all requested permissions
`find_smali_references`	Search for patterns in decompiled smali code
`get_apk_info`	Get basic APK metadata and information

📋 Specialized Analysis Prompts

Security Analysis: Comprehensive vulnerability assessment
Privacy Audit: Data collection and compliance analysis
Reverse Engineering Guide: Step-by-step analysis workflows

📦 Installation

Prerequisites

1. Java JDK 8+ (Required by Apktool)

# Ubuntu/Debian
sudo apt update && sudo apt install default-jdk

# macOS (Homebrew)
brew install openjdk

# Verify installation
java -version

2. Apktool (Core dependency)

# Option 1: Package manager (recommended)
# Ubuntu/Debian
sudo apt install apktool

# macOS
brew install apktool

# Option 2: Manual installation
# Download from https://ibotpeaches.github.io/Apktool/install/

# Verify installation
apktool --version

3. Python 3.10+

python3 --version  # Should be 3.10 or higher

Setup Instructions

1. Clone the repository

git clone https://github.com/SecFathy/APktool-MCP.git
cd APktool-MCP

2. Create virtual environment

python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

3. Install dependencies

pip install -r requirements.txt

4. Test the installation

python3 apktool_server.py
# Should start the MCP server successfully

⚙️ Configuration

Gemini CLI Integration

1. Install Gemini CLI

# Follow instructions at https://github.com/google-gemini/gemini-cli

2. Configure MCP Server

Edit your Gemini CLI configuration file:

Linux/macOS: ~/.config/gemini-cli/config.json
Windows: %APPDATA%\gemini-cli\config.json

{
  "mcpServers": {
    "apktool": {
      "command": "python3",
      "args": ["/absolute/path/to/apktool_server.py"],
      "env": {
        "APKTOOL_WORK_DIR": "/path/to/workspace"
      }
    }
  }
}

Claude Desktop Integration (Alternative)

Edit Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "apktool": {
      "command": "python3",
      "args": ["/absolute/path/to/apktool_server.py"],
      "env": {
        "APKTOOL_WORK_DIR": "/path/to/workspace"
      }
    }
  }
}

🎯 Usage Examples

Natural Language Commands

# Start Gemini CLI
gemini

# Security Analysis
> "Analyze the APK at ./suspicious_app.apk for security vulnerabilities"

# Permission Analysis  
> "What permissions does ./myapp.apk request and are any of them dangerous?"

# Code Analysis
> "Find any hardcoded API keys or secrets in ./social_app.apk"

# Privacy Audit
> "Generate a privacy compliance report for ./messenger_app.apk"

# Reverse Engineering
> "Help me understand how the authentication works in ./banking_app.apk"

Direct Tool Usage

# Decompile an APK
> Use decode_apk to decompile ./sample.apk

# Analyze permissions
> Use list_permissions on the decompiled directory ./sample

# Search for patterns
> Use find_smali_references to search for "crypto" in ./sample

# Extract strings
> Use extract_strings from ./sample for locale "en"

# Rebuild APK
> Use build_apk to recompile ./sample into ./sample_modified.apk

Guided Workflows

# Run automated security analysis
> Run the security analysis prompt on ./target_app.apk

# Perform privacy audit
> Execute privacy audit workflow for ./social_media_app.apk

# Get reverse engineering guidance
> Use the reverse engineering guide for analyzing login functionality in ./app.apk

📁 Project Structure

apktool-mcp-server/
├── apktool_server.py          # Main MCP server implementation
├── requirements.txt           # Python dependencies
├── config.json               # Example Gemini CLI configuration
├── README.md                 # This file
├── GEMINI.md                 # AI assistant context file
├── LICENSE                   # MIT license
├── examples/                 # Usage examples and samples
│   ├── sample_analysis.py    # Example analysis scripts
│   └── workflows/            # Common workflow examples
├── tests/                    # Unit tests
│   ├── test_server.py        # Server functionality tests
│   └── test_tools.py         # Individual tool tests
└── docs/                     # Additional documentation
    ├── SECURITY.md           # Security guidelines
    ├── CONTRIBUTING.md       # Contribution guidelines
    └── TROUBLESHOOTING.md    # Common issues and solutions

🔒 Security Considerations

⚠️ Important Security Notes

Legal Compliance: Only analyze APKs you own or have explicit permission to analyze
Malware Risk: Unknown APKs may contain malicious code - use in isolated environments
Data Privacy: Decompiled APKs may contain sensitive user information
Workspace Isolation: Configure dedicated workspace with restricted permissions
Process Limits: Server includes timeouts to prevent resource exhaustion

Best Practices

# Use dedicated workspace
export APKTOOL_WORK_DIR="/secure/isolated/workspace"

# Set appropriate permissions
chmod 750 /secure/isolated/workspace

# Monitor resource usage
htop  # Watch memory and CPU during analysis

# Clean up after analysis
rm -rf /secure/isolated/workspace/*

🧪 Testing

Run Unit Tests

# Install test dependencies
pip install pytest pytest-asyncio

# Run all tests
pytest tests/

# Run with coverage
pytest --cov=apktool_server tests/

Manual Testing

# Test server startup
python3 apktool_server.py

# Test with sample APK
# Download a sample APK and test basic functionality

Integration Testing

# Test Gemini CLI integration
gemini
> /tools  # Should list apktool tools
> Use decode_apk to analyze sample.apk

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

# Clone and setup development environment
git clone https://github.com/SecFathy/APktool-MCP.git
cd APktool-MCP
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
pytest

# Format code
black apktool_server.py