Kali MCP Server

A production-quality MCP (Model Context Protocol) server that exposes 20+ Kali Linux security tools through an AI-friendly interface, enabling AI assistants to perform penetration testing and security assessments in a controlled, structured manner.

⚠️ LEGAL NOTICE

This tool is intended for AUTHORIZED security testing only.

• You MUST have explicit written permission to test any systems
• Unauthorized access to computer systems is ILLEGAL
• Users are responsible for ensuring proper authorization
• The authors assume NO LIABILITY for misuse of this tool

By using this tool, you acknowledge that you have proper authorization and accept full responsibility for your actions.

Features

• 20+ Security Tools across multiple categories
• Type-safe using TypeScript and Zod validation
• Safe execution with command allowlists, timeouts, and output limits
• Input validation to prevent command injection
• Rate limiting to prevent abuse
• Structured output with proper error handling
• MCP-compliant for seamless AI integration

Supported Tools

Network Tools (6)

• nmap - Network port scanning and service detection
• nmap discover - Host discovery on networks
• masscan - High-speed port scanner
• netdiscover - ARP reconnaissance
• tcpdump - Packet capture
• tshark - Wireshark CLI for packet analysis

Web Security Tools (7)

• gobuster dir - Directory/file enumeration
• gobuster dns - Subdomain enumeration
• sqlmap - SQL injection testing
• nikto - Web server scanner
• wpscan - WordPress security scanner
• ffuf - Web fuzzer
• nuclei - Template-based vulnerability scanner

Password Tools (3)

• hydra - Network login brute-forcer
• john - John the Ripper password cracker
• hashcat - Advanced password recovery

Exploitation Tools (3)

• searchsploit - Exploit database search
• searchsploit examine - View exploit details
• msfvenom - Metasploit payload generator

Installation

Prerequisites

1. Kali Linux (or any Linux distribution with security tools installed)
2. Node.js 18+ and npm
3. Security tools installed on your system

Install Security Tools (Kali Linux)

sudo apt update
sudo apt install -y \
  nmap masscan netdiscover tcpdump tshark \
  gobuster sqlmap nikto wpscan ffuf nuclei \
  hydra john hashcat \
  exploitdb metasploit-framework

Install MCP Server

cd kali-mcp-server
npm install
npm run build

Usage

Running the Server

# Start the server
npm start

# Or run directly
node dist/index.js

Testing with MCP Inspector

# Launch the MCP Inspector for interactive testing
npm run inspector

# Or
npx @modelcontextprotocol/inspector node dist/index.js

Integrating with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "kali-security": {
      "command": "node",
      "args": ["/path/to/kali-mcp-server/dist/index.js"]
    }
  }
}

Tool Reference

Network Tools

kali_network_nmap_scan

Perform network port scanning using Nmap.

Example:

{
  "target": "192.168.1.1",
  "ports": "22,80,443",
  "scan_type": "tcp_syn",
  "timing": "normal",
  "service_version": true
}

Parameters:

• target (required): IP, hostname, or CIDR range
• ports (optional): Port specification (default: top 1000)
• scan_type: tcp_syn, tcp_connect, udp, ack, null, fin, xmas
• timing: paranoid, sneaky, polite, normal, aggressive, insane
• os_detection: Enable OS detection (requires root)
• service_version: Probe for service versions
• script_scan: NSE scripts to run
• aggressive: Enable aggressive scan
• timeout: Timeout in seconds (default: 300)

kali_network_nmap_discover

Discover live hosts on a network.

Example:

{
  "network": "192.168.1.0/24",
  "method": "ping",
  "timeout": 120
}

Web Tools

kali_web_gobuster_dir

Enumerate directories and files on web servers.

Example:

{
  "url": "https://example.com",
  "wordlist": "/usr/share/wordlists/dirb/common.txt",
  "extensions": "php,html,txt",
  "threads": 10
}

kali_web_sqlmap_test

Automated SQL injection testing.

Example:

{
  "url": "https://example.com/page?id=1",
  "level": 1,
  "risk": 1,
  "batch": true
}

WARNING: Only use on systems you have authorization to test.

Password Tools

kali_password_hydra_brute

Fast network login brute-forcer.

Example:

{
  "target": "192.168.1.1",
  "service": "ssh",
  "username": "admin",
  "password_list": "/usr/share/wordlists/rockyou.txt",
  "threads": 16
}

WARNING: Only use on systems you have authorization to test.

Exploitation Tools

kali_exploit_searchsploit_search

Search the Exploit Database.

Example:

{
  "query": "apache 2.4",
  "platform": "linux"
}

Or search by CVE:

{
  "cve": "CVE-2021-44228"
}

kali_exploit_msfvenom_generate

Generate custom payloads.

Example:

{
  "payload": "linux/x64/shell_reverse_tcp",
  "lhost": "192.168.1.100",
  "lport": 4444,
  "format": "elf"
}

Security Features

Command Allowlist

Only pre-approved commands can be executed. The server maintains a strict allowlist of permitted security tools.

Input Validation

All inputs are validated before execution:

• IP addresses and CIDR ranges
• Hostnames and URLs
• Port numbers and ranges
• File paths (no directory traversal)
• No shell metacharacters

Output Sanitization

Sensitive information is automatically redacted from output:

• Passwords
• API keys
• Tokens
• Secrets

Execution Limits

• Timeouts: Configurable per tool (default: 5 minutes)
• Output size: Maximum 10MB per command
• Rate limiting: 10 commands per minute, 100 per hour

Process Isolation

All commands are executed in isolated child processes with:

• Separate stdout/stderr capture
• Graceful timeout handling
• Resource cleanup

Configuration

Environment Variables

Customize tool paths using environment variables:

export NMAP_PATH=/usr/bin/nmap
export GOBUSTER_PATH=/usr/bin/gobuster
export SQLMAP_PATH=/usr/bin/sqlmap
# ... etc

Wordlist Paths

Default wordlists (Kali Linux):

• /usr/share/wordlists/rockyou.txt
• /usr/share/wordlists/dirb/common.txt
• /usr/share/seclists/Discovery/Web-Content/common.txt

Error Handling

The server provides detailed, actionable error messages:

❌ Command failed: nmap -sS 192.168.1.1

🔢 Exit code: 1

📋 Error output:
You requested a scan type which requires root privileges.

Possible causes:
- TCP SYN scan requires root/sudo
- Try using scan_type="tcp_connect" instead
- Run the server with sudo (not recommended)

Suggested actions:
1. Use tcp_connect scan type (doesn't require root)
2. Grant CAP_NET_RAW capability to nmap
3. Check permissions and try again

Troubleshooting

Tools Not Found

If tools are not in your PATH:

# Check if tool is installed
which nmap

# Install missing tools
sudo apt install nmap

# Or set custom path
export NMAP_PATH=/custom/path/to/nmap

Permission Errors

Some tools require root privileges:

• nmap TCP SYN scan (-sS)
• masscan
• tcpdump/tshark
• netdiscover

Solutions:

1. Use non-privileged alternatives (e.g., nmap TCP connect scan)
2. Grant specific capabilities: sudo setcap cap_net_raw+ep /usr/bin/nmap
3. Run server with sudo (not recommended for security reasons)

Timeout Issues

If scans are timing out:

{
  "target": "192.168.1.1",
  "ports": "1-65535",
  "timeout": 1800  // Increase to 30 minutes
}

Development

Project Structure

kali-mcp-server/
├── src/
│   ├── index.ts           # Main server
│   ├── types.ts           # Type definitions
│   ├── constants.ts       # Configuration
│   ├── utils/
│   │   ├── executor.ts    # Command execution
│   │   ├── validator.ts   # Input validation
│   │   ├── formatter.ts   # Output formatting
│   │   └── parser.ts      # Output parsing
│   ├── tools/
│   │   ├── network.ts     # Network tool handlers
│   │   ├── web.ts         # Web tool handlers
│   │   ├── password.ts    # Password tool handlers
│   │   └── exploit.ts     # Exploit tool handlers
│   └── schemas/
│       ├── network.schemas.ts
│       ├── web.schemas.ts
│       ├── password.schemas.ts
│       └── exploit.schemas.ts
└── dist/                  # Compiled output

Adding New Tools

1. Define Zod schema in src/schemas/[category].schemas.ts
2. Implement tool handler in src/tools/[category].ts
3. Register tool in src/index.ts
4. Add to ALLOWED_COMMANDS in src/constants.ts

Example:

// 1. Schema
export const MyToolSchema = z.object({
  target: z.string().describe("Target to scan"),
  option: z.boolean().default(false),
});

// 2. Handler
export async function myTool(input: MyToolInput): Promise<ToolResult> {
  const args = [input.target];
  if (input.option) args.push("--option");

  const result = await executeCommand("mytool", args);
  return formatExecutionResult(result);
}

// 3. Register in index.ts
{
  name: "kali_category_mytool_action",
  description: "Description of what it does",
  inputSchema: zodToJsonSchema(MyToolSchema),
}

// 4. Add to ALLOWED_COMMANDS
export const ALLOWED_COMMANDS = new Set([
  // ... existing commands
  "mytool",
]);

Running Tests

npm run build
npm start

Test with MCP Inspector:

npm run inspector

Common Workflows

1. Network Reconnaissance

1. Discover hosts: kali_network_nmap_discover
2. Port scan: kali_network_nmap_scan
3. Service detection: kali_network_nmap_scan with service_version=true
4. Vulnerability scan: kali_network_nmap_scan with script_scan="vuln"

2. Web Application Testing

1. Directory enumeration: kali_web_gobuster_dir
2. Subdomain discovery: kali_web_gobuster_dns
3. Vulnerability scanning: kali_web_nikto_scan
4. SQL injection testing: kali_web_sqlmap_test

3. Password Assessment

1. Network brute force: kali_password_hydra_brute
2. Hash identification: Manual analysis
3. Hash cracking: kali_password_john_crack or kali_password_hashcat_crack

4. Exploit Research

1. Search exploits: kali_exploit_searchsploit_search
2. Examine exploit: kali_exploit_searchsploit_examine
3. Generate payload: kali_exploit_msfvenom_generate

Performance Tips

1. Use appropriate timing: Balance speed vs stealth
2. Limit port ranges: Scan only necessary ports
3. Use wordlists wisely: Smaller wordlists for faster results
4. Adjust threads: More threads = faster, but more resource-intensive
5. Set realistic timeouts: Complex scans need more time

Contributing

Contributions are welcome! Please ensure:

• All inputs are validated
• Commands are in the allowlist
• Error messages are actionable
• Documentation is updated
• Security best practices are followed

License

MIT License - See LICENSE file for details

Acknowledgments

• Kali Linux team for the excellent security distribution
• Anthropic for the Model Context Protocol
• Security tool authors: nmap, gobuster, sqlmap, hydra, john, hashcat, and many more

Disclaimer

This tool is provided for educational and authorized security testing purposes only. The authors are not responsible for any misuse or damage caused by this tool. Always ensure you have proper authorization before testing any systems.

---

Version: 1.0.0 Last Updated: 2025-11-29