Summary: Hercules MCP gives a terminal-capable AI agent an on-demand Kali Linux container exposing 47 structured security tools plus stealth browser automation, with evidence persisted in a session-owned host workspace.
Session & shell control — explicitly start/stop the container, spin up fresh sessions, list sessions, inspect networking, run foreground/background shell commands, manage jobs, and read/write/inspect workspace files offline.
Reconnaissance — DNS lookups (dig/dnsx, zone transfer), WHOIS registration data, and Amass passive/active/brute subdomain enumeration.
Network & protocols — Nmap scans (quick/aggressive/port/script/custom), authoring and running custom NSE scripts, curl HTTP requests, ncat connect/listen/interact, and hping3 packet crafting.
Web & API testing — fingerprinting (httpx, WhatWeb, wafw00f, Nikto, WPScan, Arjun), directory fuzzing (Gobuster/ffuf), vuln scanning (Dalfox/Commix), Nuclei runs plus custom template authoring, and SQLMap scanning/enumeration/dumping/OS commands.
Exploit research — SearchSploit lookups and optional Metasploit module search, execution, payload generation, handlers/listeners, and session/job management.
Credentials — Hydra online credential testing and John the Ripper offline hash cracking.
Files & binary triage — Binwalk firmware analysis/extraction, Steghide payload inspection/extraction, and shell-accessible hex/binutils tooling.
Browser automation — ten browser_* tools for navigation, accessibility-tree snapshots, element actions, page reads, screenshots, JavaScript eval, conditional waits, isolated session/stream management, built-in skill docs, and a raw command escape hatch.
Provides access to the Metasploit Framework for exploitation, using native RPC to execute modules and manage sessions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hercules MCP scan example.com for open ports and services"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Hercules gives terminal-capable AI agents structured MCP access to security tools and Obscura browser automation. An agent starts its own Kali container only when needed. Results and evidence stay in a session-owned workspace on your host.
Use cases: authorized penetration testing · CTF and forensics · vulnerability research · browser automation · basic binary and firmware triage.
Authorized use only. Use Hercules only on systems you are permitted to test. The full Kali image and privileged shell do not grant target authorization.
Paste this prompt into the terminal-capable agent you want to configure:
Install or update Hercules MCP via https://github.com/0xMihirK/hercules-mcp/blob/main/install.md. Configure only this agent. Host setup does not start containers. Ask: prebuilt image (recommended) or local build. Prepare runtime after my choice. Stop and report denials.The installation guide covers supported clients, Windows/macOS/Linux bootstrap commands, updates, repair, and recovery. Host setup needs Git and uv; it does not start Docker. Your agent asks you to choose a pinned prebuilt Kali image (recommended) or a local build before runtime preparation. Container verification is separate. Updates preserve client settings and evidence, and keep the working version active until a replacement is ready.
Clients: Claude Code/Desktop, Codex, Cursor, VS Code, Gemini CLI, OpenCode, Windsurf, Hermes, and other local STDIO MCP clients through a generic export.
Related MCP server: Kali MCP Server
Your agent connects to the Hercules host server over STDIO. The connection exposes tools and resources without creating a container. system_start_container explicitly starts or reuses the session-owned Kali runtime; the current host workspace is mounted there so evidence survives a stop.
One full image contains all tool bundles. Capability settings control which MCP tools an agent sees; they do not remove packages from the image. The full profile has 47 tools, 5 resources, and 2 lookup templates. With Metasploit disabled it has 42 tools; core-only has 12.
Area | What the agent can use |
Session, shell and evidence | Explicit start/stop, owned background jobs, |
Reconnaissance | DNS, WHOIS and Amass for host, domain and ASN discovery. |
Network and protocols | Nmap and NSE authoring, HTTP, Ncat and Hping3. |
Web and APIs | WhatWeb, Nikto, WAF detection, ffuf/Gobuster, Dalfox/Commix, Nuclei and SQLMap. |
Exploit research | SearchSploit; optional Metasploit search, modules, payloads and listeners. Version applicability still needs source checks. |
Credentials | Hydra for authorized online checks and John the Ripper for offline hashes. |
Files and binary triage | Binwalk, Steghide, ExifTool, hex utilities and shell-accessible binutils. Basic triage, not a full decompiler. |
Browser automation | Ten |
Core: shell_exec, shell_exec_background, shell_check_job, shell_kill_job, system_start_container, system_start_new_session, system_list_sessions, system_stop_container, system_network_info, workspace_read_file, workspace_write_file, workspace_inspect.
Recon: recon_dns, recon_whois, recon_amass.
Network: nmap_scan, nmap_write_nse_script, nmap_run_nse_script, network_curl, ncat, network_hping3.
Web: web_scan, fuzz_dirs, web_vuln_scan, nuclei_run, nuclei_write_template, sqlmap_run.
Exploit research: searchsploit, metasploit_search, metasploit_run_module, metasploit_manage, metasploit_generate_payload, metasploit_start_listener.
Credentials and files: bruteforce_hydra, crack_john, ctf_binwalk, ctf_steghide.
Browser: browser_open, browser_snapshot, browser_act, browser_read, browser_screenshot, browser_eval, browser_wait, browser_session, browser_skill, browser_cmd.
The five post-exploitation resources cover LinPEAS, WinPEAS, PowerUp, GTFOBins and LOLBAS. Two templates let agents look up individual GTFOBins or LOLBAS entries without loading their entire databases. Read the detailed tool guide.
Hercules also packages nine portable skills. The general Hercules workflow and operator guidance route work to the right tools; detailed references load only when relevant.
Hercules MCP · Operator · Nmap NSE · Nuclei · Application testing · Infrastructure · Wireless and embedded · Binary analysis · Assessment operations
The skills help agents choose tools, preserve complete diagnostics, verify findings against controls, coordinate workers and confirm cleanup. They do not add hardware or authorize an assessment.
Repeated starts reuse the current workspace. system_stop_container stops the runtime while keeping its files. system_start_new_session creates a new, stopped workspace; files from earlier sessions remain inspectable but do not move automatically. workspace_inspect works even when Docker is stopped.
Hercules does not enforce a target allowlist. Structured tools check target syntax, and the host-network browser has no SSRF boundary. Keep operations within your authorized scope.
Obscura does not enforce CSP and does not support native browser downloads. Use HTTP or shell workflows for authorized downloads, then verify saved files. Browser behavior is not proof of Chromium-equivalent behavior.
shell_exec and advanced browser commands can bypass structured-tool safeguards. Container-layer tool installs are temporary; keep custom scripts, virtual environments and dependency notes in the workspace.
Results may be filtered or paged. Check output_complete, evidence_complete and cleanup confirmation before drawing conclusions.
For configuration, security details, workspace migration and troubleshooting, use the detailed guide. For the exact install/update workflow, use install.md.
If Hercules is useful, please star the repository. Found a bug or have an improvement? Open an issue or send a focused pull request with the behavior and tests you changed. Contributions to tool reliability, agent guidance and documentation are welcome.
Hercules is MIT licensed. See the acknowledgements for its runtime and tool dependencies.
Purpose: Interact with a page element: click, fill, type, press a key, hover, select an option, or (un)check.… Constraints: Use browser_snapshot refs when available. ref/CSS supports all actions. Semantic role/text/label supports click, fill, check, and hover only; use name/exact for accessible matching. Example: browser_act(action='fill', target='e3', value='admin', session='recon')
Inputs: action (required), name, exact, value, +3 more. Returns: object
Purpose: Escape hatch that runs ANY agent-browser command against the current stealth session — giving access to the COMPLETE browser… Constraints: Call browser_skill(name='core', full=True) first. args is raw administrator input for controller features absent from structured tools… Example: browser_cmd(args='cookies list', session='recon')
Inputs: args (required), json, session, timeout. Returns: object
Purpose: Run arbitrary JavaScript in the page context and return the result. Use for custom DOM extraction, probing JS state… Constraints: The JS is written to a workspace temp file and evaluated to avoid quoting issues. Return a JSON-serializable value (wrap objects in JSON.stringify) for clean output.… Example: browser_eval(js="JSON.stringify({wd: navigator.webdriver, plugins: navigator.plugins.length})"…
Inputs: js (required), session. Returns: object
Purpose: Open a URL in cloakbrowser Chromium and start an interactive browsing session.… Constraints: url is scope-validated and redirects are revalidated. fingerprint is compatibility-only and non-empty values are rejected. Proxy precedence is parameter, BROWSER_PROXY_URL, then direct… Example: browser_open(url='https://app.target.test/login', session='recon', timezone='America/New_York'…
Inputs: url (required), proxy, locale, session, +2 more. Returns: object
Purpose: Read data from the page: visible text, inner HTML, an input value, or the page-level URL/title.… Constraints: url/title are page-level. ref/CSS supports text/html/value; semantic role/text/label supports text only with optional name/exact. Use snapshot/ref or CSS for unsupported combinations. Example: browser_read(what='url', session='recon')
Inputs: what (required), name, exact, target, +2 more. Returns: object
Purpose: Capture a validated PNG screenshot of the current page as native inline MCP image content and save it into the container work… Constraints: Shots save to /opt/workspace/browser// by default. A relative path resolves under that per-session directory and rejects '..'. full=True captures the scrollable page.… Example: browser_screenshot(session='recon')
Inputs: full, path, session, annotate, +1 more.
Purpose: Manage isolated stealth browser identities and the optional loopback-only live-view stream. Each session has its own cookies… Constraints: action selects current, list, close, close_all, or stream. Stream discovers the selected session's loopback WebSocket and safely relays it to the configured host port.… Example: browser_session(action='list')
Inputs: action (required), session, stream_port. Returns: object
Purpose: Load agent-browser's own built-in skill documentation — the authoritative… Constraints: With no name it lists available skills; name='core' (default) with full=True returns the complete command reference.… Example: browser_skill()
Inputs: full, name. Returns: object
Purpose: Capture the page's accessibility tree as compact text with stable element references (@e1, @e2, ...).… Constraints: compact is default; detailed requests an uncompacted unlimited-depth tree. Use interactive, include_urls, depth, or selector to narrow/expand it. Iframes auto-inline… Example: browser_snapshot(session='recon')
Inputs: depth, compact, session, detailed, +4 more. Returns: object
Purpose: Wait for a condition before continuing: an element/selector to appear, a fixed number of milliseconds, specific text… Constraints: condition selects the mode: selector (CSS/@ref in value), ms (milliseconds in value), text (value is the text to await), url (value is a URL glob like '**/dashboard')… Example: browser_wait(condition='load', value='networkidle', session='recon')
Inputs: condition (required), value, session. Returns: object
Purpose: Run Hydra for online credential testing against a service. Constraints: Requires target, service, usernames, and passwords. Prefix usernames/passwords with file: for wordlists. Target is validated. Output summary keeps credential findings. Example: bruteforce_hydra(target='host', service='ftp', usernames='msfadmin', passwords='msfadmin')
Inputs: target (required), service (required), passwords (required), usernames (required), +2 more. Returns: object
Purpose: Run John the Ripper against supplied hashes using a wordlist. Constraints: Hashes are written to a temporary workspace file, cracked with john, shown with john --show, then the temp file is removed. Use format and extra_args when hash type needs explicit selection. Example: crack_john(hashes='$y$j9T$...', format='crypt', wordlist='/usr/share/wordlists/rockyou.txt')
Inputs: hashes (required), format, wordlist, extra_args. Returns: object
Purpose: Analyze and optionally extract firmware, archives, and embedded files with binwalk. Constraints: extract=True adds extraction flags and --run-as=root unless extra_args already specifies --run-as. Absolute paths extract from their containing directory to avoid duplicate paths. Example: ctf_binwalk(filepath='/opt/workspace/sample.bin', extract=True)
Inputs: filepath (required), extract, extra_args. Returns: object
Purpose: Inspect or extract steghide payloads with action=info|extract. Constraints: Pass filepath and optional passphrase. Without a passphrase Hercules passes an empty one to avoid an interactive prompt. extra_args can tune steghide behavior. Example: ctf_steghide(action='info', filepath='/opt/workspace/image.jpg')
Inputs: action (required), filepath (required), extra_args, passphrase. Returns: object
Purpose: Discover web paths with gobuster or ffuf while preserving thread control. Constraints: Requires target_url. tool defaults to gobuster; ffuf is selected with tool='ffuf'. threads controls native fuzzer concurrency. Missing wordlists return repair guidance and example paths.… Example: fuzz_dirs(target_url='http://host', wordlist='/usr/share/wordlists/dirbuster/directory-list-2.3-medium.tx…
Inputs: target_url (required), tool, threads, wordlist, +3 more. Returns: object
Purpose: Generate a payload through Metasploit RPC or msfvenom fallback. Constraints: Pass payload and options such as LHOST/LPORT. format controls output format. Successful RPC generation writes payload bytes into /opt/workspace/payloads/. Example: metasploit_generate_payload(payload='linux/x86/meterpreter/reverse_tcp'…
Inputs: options (required), payload (required), format. Returns: object
Purpose: Manage Metasploit sessions and jobs with action=list_sessions|interact_session|close_session|list_jobs|stop_job. Constraints: interact_session requires session_id and command. close_session requires session_id. stop_job requires job_id.… Example: metasploit_manage(action='list_sessions')
Inputs: action (required), job_id, command, timeout, +1 more. Returns: object
Purpose: Run a Metasploit exploit, auxiliary, or post module through the RPC API. Constraints: module_type is usually exploit, auxiliary, or post. options should contain module datastore options such as RHOSTS/RPORT/TARGETURI. payload and payload_options are used for exploits.… Example: metasploit_run_module(module_type='exploit', module_name='unix/ftp/vsftpd_234_backdoor'…
Inputs: options (required), module_name (required), module_type (required), payload, +1 more. Returns: object
Purpose: Search Metasploit exploit, auxiliary, and post modules by keyword, service name, or CVE. Constraints: Returns available modules that may help with the query. Broaden the query if the list is empty. Metasploit must be enabled and RPC available. Example: metasploit_search(query='vsftpd')
Inputs: query (required). Returns: object
Purpose: Start exploit/multi/handler as a Metasploit background job. Constraints: Requires payload_type, lhost, and lport. lport must be 1-65535. Use system_network_info first to choose LHOST/LPORT on bridge-networked hosts. Manage jobs with metasploit_manage. Example: metasploit_start_listener(payload_type='linux/x86/meterpreter/reverse_tcp', lhost='10.0.0.1', lport=4444)
Inputs: lhost (required), lport (required), payload_type (required), options. Returns: object
Purpose: Use ncat with action=connect|listen|interact for TCP/UDP connections and background listeners. Constraints: connect requires target and port and runs foreground. listen can run foreground or background; background=True creates a job_id and pipe.… Example: ncat(action='listen', port=4444, job_id='listener1')
Inputs: action (required), udp, port, job_id, +7 more. Returns: object
Purpose: Make HTTP requests with curl using methods, headers, cookies, data, redirects, and extra curl arguments. Constraints: The URL is target-validated. Output is mostly raw aside from terminal cleanup and truncation. Use headers as comma-separated Header: value strings.… Example: network_curl(url='http://host/path', method='POST', data='a=1', cookie='sid=1')
Inputs: url (required), data, cookie, method, +4 more. Returns: object
Purpose: Craft packets with hping3 for firewall, service, or packet-level testing. Constraints: Requires target. count, syn, port, and extra_args map to hping3. Runs with light concurrency and target validation. Example: network_hping3(target='host', count=3, syn=True, port=80)
Inputs: target (required), syn, port, count, +1 more. Returns: object
Purpose: Run a previously written custom NSE script against a validated target. Constraints: Requires target and script_name. extra_args can pass -p, -sV, --script-args, --script-trace, -d, or -v. XML output is parsed when possible, preserving script output fields. Example: nmap_run_nse_script(target='host', script_name='http-custom-check', extra_args='-p80 --script-trace')
Inputs: target (required), script_name (required), extra_args. Returns: object
Purpose: Run Nmap using mode=quick|aggressive|port|script|custom for host discovery, service enumeration, NSE execution… Constraints: quick/aggressive/port/script require target. port requires ports. script requires scripts. extra_args is preserved for quick, aggressive, port, and script modes.… Example: nmap_scan(mode='quick', target='scanme.nmap.org')
Inputs: mode (required), ports, target, scripts, +2 more. Returns: object
Purpose: Write a custom NSE script into the container and update the Nmap script database. Constraints: Pass name without path separators; Hercules sanitizes it and writes /opt/workspace/nmap-scripts/.nse. Use nmap_run_nse_script to execute that managed artifact.… Example: nmap_write_nse_script(name='http-custom-check', content='description = [[...]]\nauthor = ...')
Inputs: name (required), content (required). Returns: object
Purpose: Run Nuclei templates against one or more targets with JSONL output. Constraints: targets is comma-separated. templates can point to a workspace template from nuclei_write_template or installed template paths. severity, tags, rate_limit, and extra_args tune execution.… Example: nuclei_run(targets='http://host', templates='/opt/workspace/nuclei-templates/check.yaml', rate_limit=5)
Inputs: targets (required), tags, severity, templates, +3 more. Returns: object
Purpose: Write a custom Nuclei YAML template into /opt/workspace/nuclei-templates. Constraints: Path traversal is rejected. Use relative paths such as custom/check.yaml. Validate with nuclei -validate via shell_exec or run with nuclei_run using the returned path. Example: nuclei_write_template(path='custom/basic-detect.yaml', content='id: basic-detect\ninfo: ...')
Inputs: path (required), content (required). Returns: object
Purpose: Enumerate subdomains with amass using passive, active, and brute-force modes. Constraints: Requires domain and validates it. active=False uses passive mode. brute=True enables brute force. This is heavy and can take up to 20 minutes. Example: recon_amass(domain='example.com', active=False)
Inputs: domain (required), brute, active, extra_args. Returns: object
Purpose: Run DNS lookups with tool=dig|dnsx for single-record queries or bulk resolution. Constraints: dig uses target, record_type, server, short, axfr, and extra_args. dnsx uses domains or target and silent/extra_args.… Example: recon_dns(tool='dig', target='example.com', record_type='MX', short=True)
Inputs: tool (required), axfr, short, server, +5 more. Returns: object
Purpose: Collect WHOIS registration data for a domain. Constraints: Use include_raw=True if registry boilerplate or exact legal text is needed. Default output preserves registrar, dates, nameservers, statuses, DNSSEC… Example: recon_whois(domain='example.com')
Inputs: domain (required), extra_args, include_raw. Returns: object
Purpose: Search or mirror Exploit-DB entries with action=search|get. Constraints: Search returns JSON when available and may degrade overly specific queries to broader terms. include_raw=True avoids result capping.… Example: searchsploit(action='search', query_or_id='apache 2.4')
Inputs: action (required), query_or_id (required), include_raw. Returns: object
Purpose: Read status and tail output from a background shell job. Constraints: Requires job_id. tail_lines controls how much recent output is returned. If output is too short, increase tail_lines or inspect artifacts with workspace_read_file/shell_exec. Example: shell_check_job(job_id='http8000', tail_lines=100)
Inputs: job_id (required), tail_lines. Returns: object
Purpose: Execute a non-interactive shell command inside the Kali container. Constraints: raw=True disables semantic compaction but retains safety bounds and artifacts. This is non-interactive; use shell_exec_background or ncat/listeners for long-running jobs. Example: shell_exec(command='id && pwd')
Inputs: command (required), raw, timeout. Returns: object
Purpose: Start a long-running shell command as a background job. Constraints: Requires job_id. Use shell_check_job to read output and shell_kill_job to stop the process. Background jobs share the current container session. Example: shell_exec_background(command='python3 -m http.server 8000', job_id='http8000')
Inputs: job_id (required), command (required). Returns: object
Purpose: Stop a background shell job by job_id. Constraints: Requires job_id. Use shell_check_job first if you need final output. The response says whether a process was killed. Example: shell_kill_job(job_id='http8000')
Inputs: job_id (required). Returns: object
Purpose: Run sqlmap with action=scan_basic|scan_custom|enumerate|dump|os_cmd. Constraints: Requires target_url and target validation. Always uses --batch and a workspace output directory. scan_custom supports method, data, cookies, level, risk, techniques, tamper, proxy, forms… Example: sqlmap_run(action='scan_basic', target_url='http://host/item?id=1')
Inputs: action (required), target_url (required), db, data, +13 more. Returns: object
Purpose: List Hercules session workspaces on the host. Constraints: Returns active_session, total_sessions, and per-session metadata where available. Does not modify the container. Example: system_list_sessions()
Inputs: no named parameters. Returns: object
Purpose: Inspect host/container networking, browser host access, and callback routes. Constraints: Returns effective RPC/listener/stream ports, LHOST guidance, localhost scope, and the Docker-host alias. Concurrent IDE clients may receive different ports. Example: system_network_info()
Inputs: no named parameters. Returns: object
Purpose: Start a fresh Hercules container session with a clean mounted workspace. Constraints: Creates a new workspace and stops the current container. Previous host workspace data is preserved. Metasploit RPC is reinitialized when enabled. Example: system_start_new_session()
Inputs: no named parameters. Returns: object
Purpose: Stop and remove the current Hercules container while preserving workspace files. Constraints: After this tool succeeds, MCP tools that require the container cannot run until a new session is started. It stops background jobs and container-side processes. Example: system_stop_container()
Inputs: no named parameters. Returns: object
Purpose: Run one web fingerprinting scanner selected by tool=httpx|whatweb|wafw00f|nikto|wpscan|arjun. Constraints: httpx accepts urls or target and supports threads. whatweb uses agg_level. nikto supports tuning. wpscan supports enumerate and api_token. arjun supports method and threads.… Example: web_scan(tool='httpx', urls='http://a,http://b', threads=20)
Inputs: tool (required), urls, title, method, +10 more. Returns: object
Purpose: Run web vulnerability scanners selected by tool=dalfox|commix. Constraints: Requires target_url. Dalfox maps threads to --worker and supports cookie and extra_args. Commix supports data, cookie, threads when native support exists, and extra_args.… Example: web_vuln_scan(tool='dalfox', target_url='http://host/?q=1', threads=8)
Inputs: tool (required), target_url (required), data, cookie, +3 more. Returns: object
Purpose: Read a bounded file chunk inside the owned container workspace. Constraints: Relative paths resolve under /opt/workspace. Paths outside it and symlink/reparse escapes are rejected. encoding='base64' reads binary data. For large files… Example: workspace_read_file(path='nuclei-templates/custom/check.yaml')
Inputs: path (required), offset, encoding, max_bytes. Returns: object
Purpose: Atomically write content to a file in the owned container workspace. Constraints: Relative paths resolve under /opt/workspace; paths outside it and symlink/reparse escapes are rejected. Supply either content or content_base64, never both. mode defaults to 0644.… Example: workspace_write_file(path='targets.txt', content='http://host\n')
Inputs: path (required), mode, content, content_base64. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 45 tools
Most tools are clearly distinguishable by their domain prefixes (system_, nmap_, metasploit_, browser_) and specific action verbs. The only potential confusion is between web_scan and web_vuln_scan, but the descriptions clarify that one is for fingerprinting and the other for vulnerability scanning, so an agent can reliably separate them.
All tool names follow a consistent lowercase snake_case convention with a <domain>_<action> pattern, such as nmap_scan, metasploit_search, shell_kill_job, and browser_open. There are no mixed naming styles or deviations, making the naming highly predictable.
With 45 tools, this server is well above the typical 3-15 tool range and qualifies as 'too many' per the calibration. While each tool has a distinct purpose, the large number (especially 10 browser_* tools and 4 shell_* job tools) creates a heavy surface that could overwhelm agents and increases selection complexity.
The server covers the core penetration testing lifecycle comprehensively: recon, scanning, exploitation, post-exploitation, web app testing, and browser automation. Minor gaps exist, such as no workspace_list_files or workspace_delete_file, and no dedicated packet capture tool, but shell_exec provides a viable workaround for these missing operations.
Secure Linux sandboxes for AI agents, as MCP tools.
AI-security knowledge as MCP: standards-mapped tools (OWASP, NIST, MITRE) for AI agents.
Find, vet, and run MCP tools through a secure audited gateway with prompt-injection risk scoring
Hyperion — MCP tool marketplace for AI agents: web, OSINT, security, research via one key.