tengu

Tengu is an MCP server that wires Claude into a large arsenal of pentesting tools, orchestrating recon, scanning, exploitation guidance, and reporting within a safe, auditable workflow. It exposes a model-driven Copilot experience where Claude selects the appropriate tools and sequences them automatically across the PTES lifecycle, from initial recon to final reporting. The server ships with built-in safety controls (allowlists, rate limiting, audit logs, and human-in-the-loop for destructive actions) and supports auto-generated reports in Markdown, HTML, or PDF formats. To start using it, run the provided MCP server (via uv/uvx or Docker) and connect Claude Code to the MCP endpoint, then instruct Claude to perform a full pentest or a targeted assessment. The system will execute one tool per iteration and feed results back into Claude for decision-making and reporting.

Once connected, you can leverage the 35 pre-built workflows and 20 resources that Tengu exposes. For example, you can initiate a full pentest, a focused web application assessment, or an AD assessment. Claude will drive tools like Nmap, Nikto, nuclei, sqlmap, Burp/ZAP-compatible workflows, Metasploit, and other industry-standard utilities, while Tengu handles sequencing, state management, and safe-human gating where needed. You can also enable autonomous agent mode to run a fully automatic engagement from recon through report generation, with configurable model, token limits, and timeouts to balance cost and speed.

Prerequisites:

• Python 3.12 or newer
• uv (or uvx tooling) installed
• Optional: Kali/Debian for tool installation when not using Docker

1. Clone the repository and navigate to the project directory

• git clone https://github.com/rfunix/tengu.git && cd tengu

2. Install Python dependencies and external tools (manual install path)

• uv sync
• make install-tools # installs external pentesting tools (Kali/Debian required for this step)

3. Run the MCP server (stdio transport) without Docker

• uv run tengu

4. Connect Claude Code to the MCP server

• claude mcp add --scope user tengu -- uv run --directory /path/to/tengu tengu

5. Optional: configure allowed targets and stealth/proxy settings in tengu.toml

• See docs/configuration-reference.md for full options

6. If you prefer Docker (recommended for consistency)

• make docker-build
• make docker-up
• Then connect Claude to the running server (as in step 4) using the container’s exposed endpoint

Prerequisites overview:

• A working Python 3.12+ environment
• Access to uv/uvx tooling for server execution
• (Optional) Docker for containerized deployment
• Claude integration setup (Claude Code) for MCP communications

Tips and common considerations:

• Environment variables: set ANTHROPIC_API_KEY for Claude integration and TENGU_AGENT_TARGET if using autonomous agent mode.
• If using autonomous agent mode, you can tune model selection and token limits via TENGU_AGENT_MODEL, TENGU_AGENT_MAX_TOKENS, and TENGU_AGENT_TIMEOUT to control cost and performance.
• For safety, enable the human_gate to interrupt destructive actions like msf_run_module, hydra_attack, or sqlmap with high risk levels.
• The Quick Start and Docker profiles mention multiple presets (docker-lab, docker-pentest, docker-full). Use these to quickly bootstrap lab targets or real-world testing environments.
• Ensure your target networks are properly defined in the tengu.toml targets configuration and that allowed_hosts align with your testing scope.
• If running in autonomous mode, monitor cost and performance since Claude may request tool sequences that span multiple iterations; adjust the max iterations and timeouts accordingly.
• For reporting, Tengu can produce MD/HTML/PDF reports; ensure the output directory or server endpoints are accessible for viewing results.