AutoPentest-MCP

One-command autonomous-pentest box. Bundles Pentest-MCP (gateway), HexStrike-AI (backend), MobSF (mobile app scanner), and 140+ CLI tools (nmap, sqlmap, nuclei, frida, msfconsole, …) behind a single MCP server. Drive it from Claude Code, Gemini CLI, OpenAI, DeepSeek, Ollama, or any MCP-capable client.

System requirements

Resource	Minimum	Recommended
OS	Kali / Debian 12+ / Ubuntu 22.04+	Kali Rolling
RAM	4 GB	8 GB+
Disk	20 GB free (~10 GB image)	40 GB+
CPU	2 cores	4 cores+
Network	apt, GitHub, PyPI, cargo, gem reachable	—
Time	30–45 min native, 45–60 min Docker build	—
Sudo	Required (passwordless for `--non-interactive`)	—

Tight on memory? Cargo and Nuclei builds are the first things to OOM — see docs/TROUBLESHOOTING.md for the prebuilt-binary workarounds the installer already applies.

Prerequisites

You need an AI client installed before running the installer — install.sh only writes the MCP config file for it; it does not install the client itself. Pick one:

AI client	Install command	Cost
Claude Code (recommended — native MCP)	`npm install -g @anthropic-ai/claude-code`	Anthropic API key or Claude.ai Pro/Max plan
Codex CLI (OpenAI's coding agent, native MCP)	`npm install -g @openai/codex`	OpenAI API key (or any OpenAI-compatible endpoint)
Antigravity CLI (`agy` — Gemini CLI's successor, native MCP)	Download installer from https://antigravity.google/download	Free with personal Google account (preview)
Gemini CLI (native MCP) ⚠️ deprecated — see note below	`npm install -g @google/gemini-cli`	Free tier with Google account (until June 18, 2026)
mcp-cli (generic bridge — DeepSeek, Ollama, Groq, Together, any OpenAI-compatible API)	Auto-installed by `./install.sh --client=mcp-cli`	Bring your own API key, or run Ollama locally
Cursor / Continue.dev / Cline (IDE plugins, native MCP)	Install from the IDE marketplace	Varies

⚠️ Gemini CLI deprecation (June 18, 2026): Google is sunsetting Gemini CLI for free, Pro, and Ultra users on June 18, 2026 in favor of Antigravity CLI (agy, download). Gemini Code Assist Standard/Enterprise and paid API key users keep access. install.sh auto-detects agy and prefers it over gemini; if you're starting fresh today, install Antigravity instead of Gemini CLI.

If none of these are on your PATH, install.sh still writes the Claude Code MCP entry but warns you — you'll need to install Claude Code afterward to actually use it.

First-run auth

After installing your AI client, sign in or set an API key before asking it to list MCP tools — otherwise the AI errors out on its own auth and it looks like the MCP is broken:

Client	One-time setup
Claude Code	`claude /login` (Pro/Max plan) — or `export ANTHROPIC_API_KEY=sk-ant-...`
Codex CLI	`export OPENAI_API_KEY=sk-...` (also accepts `OPENAI_BASE_URL` for compatible endpoints)
Antigravity (`agy`)	Launch `agy` once → Google sign-in (free with personal account during preview)
Gemini CLI	Launch `gemini` once → Google sign-in — or `export GEMINI_API_KEY=...` for paid API
mcp-cli	Set the provider key: `export OPENAI_API_KEY=...`, `DEEPSEEK_API_KEY=...`, etc. — or run Ollama locally

Quick start

# Debian/Ubuntu only — Kali already ships with git:
sudo apt install -y git

git clone --recurse-submodules https://github.com/aamirizwann/AutoPentest-MCP.git
cd AutoPentest-MCP
./install.sh

About 20–40 minutes on a fresh Kali, longer on Debian/Ubuntu. install.sh runs verify.sh automatically as its final phase, so a green summary means you're ready to use the MCP.

What you get

Layer	What	Port
MCP gateway	`pentest-mcp` — exposes 7 high-level pentest commands	8000
Backend	`hexstrike-ai` — orchestrates 127 underlying tools	8888
Mobile scanner	`MobSF` — full mobile app static + dynamic analysis	8081
CLI toolchain	nmap, sqlmap, nuclei, hydra, hashcat, msfconsole, frida, adb, apktool, jadx, … (140+ binaries)	—

After install, ask your AI client:

"Recon scanme.nmap.org and tell me what services are exposed."

"Run a full web pentest against the OWASP Juice Shop demo and summarize findings."

"Analyze /targets/SuspiciousApp.apk with MobSF and tell me if it leaks credentials."

The AI invokes the MCP, which orchestrates the toolchain, which returns structured results. No manual nmap -sV ... typing.

Supported hosts

OS	Install path
Kali Linux (rolling, ≥2024)	`./install.sh` — fastest
Debian 12+ / Ubuntu 22.04+	`./install.sh` — adds Kali repo for security tools
macOS / Windows	`cd docker && docker compose up -d --build`

Supported AI clients

Client	Native MCP?	Configured by
Claude Code	✓	`./install.sh` (auto-detects)
Codex CLI (OpenAI)	✓	`./install.sh --client=codex` (auto-detected when `codex` is on PATH)
Antigravity CLI (`agy`)	✓	`./install.sh --client=antigravity` (auto-detected when `agy` is on PATH)
Gemini CLI ⚠️ deprecated June 18, 2026	✓	`./install.sh --client=gemini`
DeepSeek / Ollama / Groq / Together / any OpenAI-compatible API (via mcp-cli)	bridged	`./install.sh --client=mcp-cli --mcp-cli-provider=deepseek`
Cursor / Continue.dev / Cline	✓	manual snippet (see ai-clients/ide-clients)

Want all currently-supported clients configured at once: ./install.sh --client=all.

Install flags

./install.sh                           # default: auto-detect client, install everything
./install.sh --no-mobile               # skip mobile pentest stack (adb, frida, etc.)
./install.sh --no-mobsf                # skip MobSF (it's heavy: poetry + ~500 MB venv)
./install.sh --client=gemini           # configure Gemini CLI instead of Claude Code
./install.sh --client=mcp-cli \        # use DeepSeek via mcp-cli
             --mcp-cli-provider=deepseek
./install.sh --ntp-region=eu           # use European NTP pool instead of Malaysia
./install.sh --skip-system-configs     # don't touch /etc (SSH keepalive, sysctl, sudo timeout)
./install.sh --non-interactive         # for CI / unattended installs (assumes passwordless sudo)

Verify

install.sh already invokes this as its final phase — you don't need to run it again right after install. Re-run it manually after a reboot, config change, or when troubleshooting:

./verify.sh

Exits 0 only when:

All systemd services (pentest-mcp, pentest-hexstrike, mobsf) are active
MCP gateway answers JSON-RPC on port 8000
HexStrike reports ≥ 105 tools available (host installs typically reach 114+; container baseline is ~108)
MobSF web UI returns HTTP 302 on port 8081
Critical CLIs (nmap, sqlmap, nuclei, hydra, hashcat, msfconsole, adb, apktool, jadx, frida, objection, mobsf) are on PATH

Using it

Once verify.sh passes, the MCP server is running and your chosen AI client has been wired to it. Here's how to actually drive it:

1. Restart your AI client

The MCP entry was written to its config file:

Client	Config path
Claude Code	`~/.claude.json`
Codex CLI	`~/.codex/config.toml`
Antigravity	`~/.gemini/antigravity/mcp_config.json`
Gemini CLI	`~/.gemini/settings.json`
mcp-cli	`~/.mcp-cli/server_config.json`

Restart the client (or close and reopen the Antigravity / Cursor IDE) so it picks up the new server.

2. Confirm the MCP is loaded

In your AI client, ask:

"List the available MCP tools."

You should see entries like recon_target, web_recon, web_exploit, pentest_target, run_command_sync, start_job, and check_job_status.

3. Run your first scan

Try one of these prompts (all hit safe, authorized targets):

"Use the MCP to recon scanme.nmap.org and tell me what services are exposed."

"Run a quick web recon against https://juice-shop.herokuapp.com and summarize the top three findings."

"Drop /path/to/SampleApp.apk into MobSF and tell me whether it leaks API keys or uses cleartext HTTP."

The AI will pick the right MCP tool, send arguments to the gateway on :8000, which calls HexStrike on :8888, which runs the underlying CLI. Results come back as structured JSON for the AI to summarize.

4. Long-running scans

Anything over ~5 minutes (full nuclei sweeps, hashcat runs, MobSF dynamic analysis) is exposed via start_job + check_job_status so the AI can poll instead of timing out. The AI handles this automatically — you don't need to babysit.

5. Stopping / restarting services

systemctl --user stop  pentest-mcp pentest-hexstrike mobsf
systemctl --user start pentest-mcp pentest-hexstrike mobsf
systemctl --user status pentest-mcp pentest-hexstrike mobsf
journalctl --user -u pentest-mcp -f      # tail gateway logs

Services come back automatically on reboot (via loginctl enable-linger).

Architecture

┌─────────────┐      ┌──────────────────┐      ┌──────────────┐      ┌────────────┐
│  AI client  │ MCP  │  pentest-mcp     │ HTTP │  hexstrike   │ exec │  140+ CLI  │
│ (Claude /   ├─────►│  gateway         ├─────►│  backend     ├─────►│  tools     │
│  Gemini /   │stdio │  :8000           │      │  :8888       │      │ (nmap,     │
│  mcp-cli)   │      │                  │      │              │      │  sqlmap,   │
└─────────────┘      └──────────────────┘      └──────────────┘      │  nuclei,…) │
                                                                     └────────────┘
                                               ┌──────────────┐
                                               │  MobSF       │  ← drop APK/IPA via web UI
                                               │  :8081       │
                                               └──────────────┘

See docs/ARCHITECTURE.md for the deep dive.

Documentation

docs/ARCHITECTURE.md — full request flow + how the bridge translates stdio↔HTTP
docs/TOOL_INVENTORY.md — the complete 140-tool table by category
docs/TARGETS.md — safe practice targets you can scan legally
docs/TROUBLESHOOTING.md — OOM during nuclei build, PEP 668 errors, port collisions, etc.
docs/SECURITY.md — authorization rules and ethical-use boundaries
docker/README.md — Docker quick-start
ai-clients/*/README.md — per-client setup details

⚠️ Authorization required

This is an offensive security toolkit. Only run it against:

Systems you own
Targets where you have explicit written authorization to test
Public training targets: scanme.nmap.org, OWASP Juice Shop, DVWA, PortSwigger labs, HackTheBox/TryHackMe machines you've reserved

Unauthorized scanning is illegal in most jurisdictions. See docs/SECURITY.md for the long version.

Credits

Pentest-MCP by @Vasanthadithya-mundrathi — the MCP gateway
HexStrike-AI by @0x4m4 — the tool-orchestration backend
MobSF — mobile app security framework
The 140+ underlying tools come from the Kali Linux project, ProjectDiscovery, and dozens of open-source maintainers

MIT licensed — see LICENSE.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
ai-clients		ai-clients
docker		docker
docs		docs
hexstrike-ai @ 9b8c780		hexstrike-ai @ 9b8c780
installers		installers
pentest-mcp @ c803a7d		pentest-mcp @ c803a7d
system-configs		system-configs
systemd		systemd
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
uninstall.sh		uninstall.sh
verify.sh		verify.sh

Navigation Menu

Repository files navigation

AutoPentest-MCP

System requirements

Prerequisites

First-run auth

Quick start

What you get

Supported hosts

Supported AI clients

Install flags

Verify

Using it

1. Restart your AI client

2. Confirm the MCP is loaded

3. Run your first scan

4. Long-running scans

5. Stopping / restarting services

Architecture

Documentation

⚠️ Authorization required

Credits

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AutoPentest-MCP

System requirements

Prerequisites

First-run auth

Quick start

What you get

Supported hosts

Supported AI clients

Install flags

Verify

Using it

1. Restart your AI client

2. Confirm the MCP is loaded

3. Run your first scan

4. Long-running scans

5. Stopping / restarting services

Architecture

Documentation

⚠️ Authorization required

Credits

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages