User (natural language)
        ↓
Local LLM — qwen2.5 via Ollama
  (decides which tools to call and with what arguments)
        ↓
MCP Client — bridges LLM decisions to real tool execution
        ↓
MCP Server — exposes Hashcat as structured tools
        ↓
Hashcat — performs actual password recovery
        ↓
Results logged to results/session_log.json

git clone https://github.com/YOUR_USERNAME/hashcat-mcp.git
cd hashcat-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

ollama pull qwen2.5:latest

cd hashcat-mcp
source venv/bin/activate
python3 mcp_client.py

You: crack this hash: 482c811da5d5b4bc6d497ffa98491e38
Assistant: [calls identify_hash → MD5 identified]
           [calls run_hashcat → password123 found]
           The password is: password123

admin:e90664c0af74160644d29e4d6147969b
user1:5f4dcc3b5aa765d61d8327deb882cf99
482c811da5d5b4bc6d497ffa98491e38

You: crack all hashes in /home/user/hashes.txt — they are MD5

==================================================
BATCH CRACK SUMMARY
==================================================
Total hashes:   3
Cracked:        3 (100.0%)
Not cracked:    0
==================================================
RESULTS:
  ✓ admin      → Summer2024
  ✓ user1      → password
  ✓ (hash)     → password123
==================================================
Full results saved to: results/session_log.json

{
  "timestamp": "2026-08-19T19:33:27.932857",
  "username": "admin",
  "hash": "e90664c0af74160644d29e4d6147969b",
  "hash_mode": 0,
  "cracked": true,
  "password": "Summer2024",
  "attack_used": "mode 6 wordlist=100k-ncsc mask=?d?d?d?d"
}

hashcat-mcp/
├── mcp_server.py        # MCP server — exposes Hashcat as tools
├── mcp_client.py        # MCP client — connects LLM to server
├── prompts/
│   └── system_prompt.txt  # LLM behavior instructions
├── hashes/              # Hash files for testing
├── results/
│   └── session_log.json   # Automatic audit log
└── requirements.txt