# Quick Start Guide
Get up and running with Kali MCP Server in 5 minutes.
## Prerequisites
- Kali Linux (or Linux with security tools)
- Node.js 18+ and npm
## Installation
```bash
# 1. Navigate to project directory
cd kali-mcp-server
# 2. Install dependencies
npm install
# 3. Build the project
npm run build
# 4. Test the server
npm run inspector
```
This will open the MCP Inspector in your browser where you can test all tools interactively.
## First Test: Scan with Nmap
In the MCP Inspector:
1. Select **kali_network_nmap_scan** from the tool list
2. Fill in the parameters:
```json
{
"target": "scanme.nmap.org",
"ports": "80,443",
"scan_type": "tcp_connect",
"timeout": 60
}
```
3. Click **Execute**
4. View the results
## Common Tasks
### 1. Port Scanning
**Quick scan:**
```json
{
"tool": "kali_network_nmap_scan",
"target": "192.168.1.1",
"ports": "22,80,443",
"scan_type": "tcp_connect"
}
```
**Full scan with service detection:**
```json
{
"tool": "kali_network_nmap_scan",
"target": "192.168.1.1",
"ports": "1-65535",
"scan_type": "tcp_connect",
"service_version": true,
"timeout": 1800
}
```
### 2. Web Directory Enumeration
```json
{
"tool": "kali_web_gobuster_dir",
"url": "https://example.com",
"wordlist": "/usr/share/wordlists/dirb/common.txt",
"threads": 10
}
```
### 3. SQL Injection Testing
```json
{
"tool": "kali_web_sqlmap_test",
"url": "https://example.com/page?id=1",
"level": 1,
"risk": 1,
"batch": true
}
```
### 4. Search for Exploits
```json
{
"tool": "kali_exploit_searchsploit_search",
"query": "wordpress 5.0"
}
```
Or by CVE:
```json
{
"tool": "kali_exploit_searchsploit_search",
"cve": "CVE-2021-44228"
}
```
### 5. Password Brute Force
```json
{
"tool": "kali_password_hydra_brute",
"target": "192.168.1.1",
"service": "ssh",
"username": "admin",
"password_list": "/usr/share/wordlists/rockyou.txt",
"threads": 4
}
```
## Integrating with Claude Desktop
1. **Find your config file:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. **Add this configuration:**
```json
{
"mcpServers": {
"kali-security": {
"command": "node",
"args": ["/absolute/path/to/kali-mcp-server/dist/index.js"]
}
}
}
```
3. **Get the absolute path:**
```bash
cd /path/to/kali-mcp-server
echo "$(pwd)/dist/index.js"
```
4. **Restart Claude Desktop**
5. **Test in Claude:**
```
Can you scan scanme.nmap.org for open ports?
```
## All Available Tools
| Category | Tool | Command |
|----------|------|---------|
| **Network** | Nmap Port Scan | `kali_network_nmap_scan` |
| | Nmap Host Discovery | `kali_network_nmap_discover` |
| | Masscan | `kali_network_masscan_scan` |
| | Netdiscover | `kali_network_netdiscover_scan` |
| | Tcpdump | `kali_network_tcpdump_capture` |
| | Tshark | `kali_network_tshark_capture` |
| **Web** | Gobuster Dir | `kali_web_gobuster_dir` |
| | Gobuster DNS | `kali_web_gobuster_dns` |
| | SQLMap | `kali_web_sqlmap_test` |
| | Nikto | `kali_web_nikto_scan` |
| | WPScan | `kali_web_wpscan_scan` |
| | ffuf | `kali_web_ffuf_fuzz` |
| | Nuclei | `kali_web_nuclei_scan` |
| **Password** | Hydra | `kali_password_hydra_brute` |
| | John the Ripper | `kali_password_john_crack` |
| | Hashcat | `kali_password_hashcat_crack` |
| **Exploit** | Searchsploit Search | `kali_exploit_searchsploit_search` |
| | Searchsploit Examine | `kali_exploit_searchsploit_examine` |
| | Msfvenom | `kali_exploit_msfvenom_generate` |
## Common Issues
### "Command not found: nmap"
```bash
sudo apt install nmap
```
### "Permission denied"
Use `tcp_connect` instead of `tcp_syn` (doesn't require root):
```json
{
"scan_type": "tcp_connect"
}
```
Or grant capabilities:
```bash
sudo setcap cap_net_raw+ep /usr/bin/nmap
```
### "Invalid wordlist path"
Use full path:
```json
{
"wordlist": "/usr/share/wordlists/dirb/common.txt"
}
```
## Default Wordlists (Kali Linux)
- Directories: `/usr/share/wordlists/dirb/common.txt`
- Passwords: `/usr/share/wordlists/rockyou.txt`
- Subdomains: `/usr/share/seclists/Discovery/DNS/subdomains-top1million-5000.txt`
- Web content: `/usr/share/seclists/Discovery/Web-Content/common.txt`
## Safety Tips
1. ✅ **Always get authorization** before scanning
2. ✅ **Start with conservative settings** (low threads, short timeouts)
3. ✅ **Test on safe targets** first (scanme.nmap.org, your own systems)
4. ✅ **Review parameters** before executing
5. ✅ **Monitor resource usage** during scans
## Example Workflow: Web App Assessment
```bash
# 1. Launch MCP Inspector
npm run inspector
# 2. Discover subdomains
Tool: kali_web_gobuster_dns
{
"domain": "example.com",
"wordlist": "/usr/share/seclists/Discovery/DNS/subdomains-top1million-5000.txt"
}
# 3. Enumerate directories
Tool: kali_web_gobuster_dir
{
"url": "https://example.com",
"wordlist": "/usr/share/wordlists/dirb/common.txt",
"extensions": "php,html,txt"
}
# 4. Scan for vulnerabilities
Tool: kali_web_nikto_scan
{
"target": "example.com",
"port": 443,
"ssl": true
}
# 5. Test for SQL injection
Tool: kali_web_sqlmap_test
{
"url": "https://example.com/page?id=1",
"level": 1,
"risk": 1
}
```
## Next Steps
- Read the full [README.md](README.md) for detailed documentation
- Check [INSTALL.md](INSTALL.md) for advanced configuration
- Review tool-specific parameters in MCP Inspector
- Join the community and contribute
## Support
- Check logs in stderr output
- Test tools manually: `nmap --help`
- Review error messages (they include suggested fixes)
- Open an issue on GitHub
---
**Remember:** This tool is for authorized security testing only. Always ensure you have proper permission before scanning any systems.
Happy (authorized) hacking! 🔒
