# mobile-security-mcp

> **Legitimate penetration testing toolkit** — for use only on applications you are authorised to test.

An MCP (Model Context Protocol) server that exposes Android security research tools as callable functions to any MCP-compatible agent (Claude Code, Cline, Goose, OpenCode).

---

## Requirements

| Tool | Type | Purpose |
|------|------|---------|
| Python 3.11+ | runtime | — |
| apktool | binary | smali decompile |
| jadx | binary | Java decompile |
| apkid | pip | packer detection |
| apkleaks | pip | secret scanning |
| frida / frida-tools | pip + binary | dynamic instrumentation |
| objection | pip | high-level Frida wrapper |
| androguard | pip | manifest parsing |
| quark-engine | pip | vulnerability analysis |
| mitmproxy | pip + binary | traffic interception |
| ripgrep (`rg`) | binary | string search |
| uber-apk-signer.jar | jar | APK signing |
| JDK 11+ | runtime | needed for jar tools |
| adb | binary | device control |

---

## Installation

```bash
# Clone / download this repo
cd mobile-security-mcp

# Install (editable mode for development)
pip install -e .

# Check which tools are available
python -m mobile_security_mcp.setup.check_tools
```

---

## Configuration

Edit `mobile_security_mcp/config.toml`:

```toml
[signing]
jar_path = "C:/path/to/uber-apk-signer.jar"

[tools]
# Override binary paths if not on PATH
apktool = "apktool"
adb = "adb"
```

---

## Agent Integration

### Claude Code (`.claude/mcp.json`)
```json
{
  "mcpServers": {
    "mobile-security": {
      "command": "python",
      "args": ["-m", "mobile_security_mcp"]
    }
  }
}
```

### Cline (VSCode settings)
```json
"cline.mcpServers": {
  "mobile-security": {
    "command": "python",
    "args": ["-m", "mobile_security_mcp"]
  }
}
```

### OpenCode (`config.toml`)
```toml
[[mcp]]
name    = "mobile-security"
command = "python"
args    = ["-m", "mobile_security_mcp"]
```

### Goose (`profiles.yaml`)
```yaml
profiles:
  android-security:
    extensions:
      - type: stdio
        cmd: python -m mobile_security_mcp
```

---

## Available Tools (33 total)

**Static analysis**: `apk_decompile`, `apk_decompile_java`, `apk_identify`, `apk_scan_secrets`, `apk_analyze_full`, `manifest_parse`, `search_strings`

**Dynamic**: `frida_spawn`, `frida_attach`, `frida_inject`, `frida_read_output`, `frida_detach`, `objection_run`

**RASP**: `rasp_identify`, `rasp_bypass`

**Device**: `adb_devices`, `adb_shell`, `adb_install`, `adb_pull`, `adb_push`, `adb_logcat_start`, `adb_logcat_read`, `adb_logcat_stop`

**Network**: `mitm_start`, `mitm_stop`, `ssl_kill_switch`

**Signing**: `apk_sign`, `apk_rebuild_sign`

**Memory**: `memory_read`, `memory_write`

**Setup**: `check_tools`, `install_tool`

---

## Knowledge Resources

Ask your agent to load these for context:

- `knowledge://detection-patterns` — root / Frida / emulator / integrity detections
- `knowledge://bypass-playbooks` — escalation ladders
- `knowledge://framework-fingerprints` — Flutter / RN / Unity / Xamarin
- `knowledge://crypto-patterns` — hardcoded keys, weak cipher patterns
- `knowledge://common-mistakes` — what juniors get wrong

---

## Prompts

| Name | Description |
|------|-------------|
| `first-look` | Ordered checklist for any new APK |
| `rasp-assess` | Full RASP assessment protocol |
| `bypass-ssl` | SSL pinning bypass escalation |
| `bypass-root` | Root detection bypass escalation |
| `bypass-frida` | Frida detection bypass escalation |
| `stuck` | Protocol when a bypass fails |

---

## Session Memory

The server maintains a per-target memory file at:

```
mobile_security_mcp/targets/<package>/memory.md
```

Use `memory_read` at session start and `memory_write` after every significant finding.

---

## Legal

This tool is for **authorised penetration testing only**. You are responsible for ensuring you have explicit written permission before testing any application.
