Kali-Security-MCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

Project Overview

MCP-Kali-Server is an MCP (Model Context Protocol) server that bridges AI agents with 200+ Kali Linux security tools. It supports penetration testing, CTF competitions, and security assessments through intelligent tool orchestration.

Architecture: v6.0 modular architecture. The system runs in local execution mode — mcp_server.py calls Kali tools directly via subprocess, no backend server needed. Core components: declarative tool_registry, structured output_parsers, hybrid_decision_engine for multi-agent routing, and session TTL auto-cleanup.

Running the System

# Start MCP server (local execution mode, default)
python mcp_server.py

# Or use the startup script (creates venv if needed, checks tool availability)
bash start.sh

# With a specific tool profile
python mcp_server.py --tool-profile strict    # minimal tools
python mcp_server.py --tool-profile compliance # default, most tools
python mcp_server.py --tool-profile full       # all tools

# Force-enable/disable specific modules
python mcp_server.py --enable-module pwn --disable-module apt

# SSE mode for remote access
python mcp_server.py --transport sse --host 0.0.0.0 --port 8765

# Check system status
python status_check.py

The MCP configuration is in .mcp.json. Virtual environment is at .venv/.

Installing Dependencies

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Optional: PWN tools
pip install pwntools

Testing

pytest                         # run all tests
pytest -x                      # stop on first failure
pytest --cov=kali_mcp          # with coverage
pytest -k "test_name"          # run specific test

Core Architecture

mcp_server.py (520 lines, entry point)
│   Creates FastMCP instance, initializes multi-agent system,
│   registers all tools via register_xxx_tools() pattern
│
├── kali_mcp/core/              Core logic (15+ modules)
│   ├── local_executor.py       LocalCommandExecutor — subprocess tool execution
│   ├── mcp_session.py          SessionContext + StrategyEngine
│   ├── agent_registry.py       Multi-agent registry (v4.0)
│   ├── agent_coordinator.py    Central coordinator agent
│   └── ...                     AI context, ML optimizer, knowledge graph, etc.
│
├── kali_mcp/mcp_tools/         MCP tool registration (28 modules, 200+ tools)
│   Each module exports register_xxx_tools(mcp, executor, ...) function
│
├── kali_mcp/agents/            17 specialized agents
│   ├── information_gathering/  ReconAgent, SubdomainAgent, WebReconAgent
│   ├── vulnerability_discovery/ VulnScanner, WebVuln, Auth, NetworkVuln, VulnVerifier
│   ├── exploitation/           ExploitAgent, PrivilegeAgent, LateralAgent
│   └── specialized/            PwnAgent, CryptoAgent, ForensicsAgent, CodeAudit, etc.
│
├── kali_mcp/security/          Authorization & compliance
│   ├── engagement.py           EngagementContext — scope/authorization management
│   └── tool_profile.py         Tool profiles: strict | compliance | full
│
├── kali_mcp/diggers/           Deep vulnerability diggers (v3.0)
├── deep_test_engine/           HTTP/WebSocket/gRPC interaction engine
└── pwnpasi/                    PWN automation (ROP, heap exploit, fuzzing)