APKtool MCP server for AI agents

Apktool MCP Server is a powerful integration that exposes Apktool functionality through the Model Context Protocol (MCP), allowing for Android APK analysis and reverse engineering. It works with Gemini CLI to provide AI-powered security analysis, privacy auditing, and reverse engineering guidance through natural language commands.

Installation

Prerequisites

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

Apktool (Core dependency)

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

# macOS
brew install apktool

# Verify installation
apktool --version

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

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/*

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "apktool" '{"command":"python3","args":["/absolute/path/to/apktool_server.py"],"env":{"APKTOOL_WORK_DIR":"/path/to/workspace"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect