# Installation Guide for Kali MCP Server
## Prerequisites
### 1. Install Node.js and npm
#### On Kali Linux / Debian / Ubuntu:
```bash
# Update package list
sudo apt update
# Install Node.js (v20 recommended)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Verify installation
node --version # Should show v20.x.x
npm --version # Should show 10.x.x
```
#### On macOS:
```bash
# Using Homebrew
brew install node
# Verify installation
node --version
npm --version
```
#### On other Linux distributions:
```bash
# Using NodeSource repository
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs
# Or use your package manager
```
### 2. Install Security Tools
#### On Kali Linux (All tools pre-installed):
Kali Linux comes with most security tools pre-installed. Update them:
```bash
sudo apt update && sudo apt upgrade -y
```
#### On Ubuntu / Debian:
```bash
sudo apt update
# Network tools
sudo apt install -y nmap masscan netdiscover tcpdump tshark
# Web tools
sudo apt install -y gobuster nikto
sudo apt install -y sqlmap wpscan
# Install ffuf
wget https://github.com/ffuf/ffuf/releases/download/v2.1.0/ffuf_2.1.0_linux_amd64.tar.gz
tar -xzf ffuf_2.1.0_linux_amd64.tar.gz
sudo mv ffuf /usr/local/bin/
sudo chmod +x /usr/local/bin/ffuf
# Install nuclei
wget https://github.com/projectdiscovery/nuclei/releases/download/v3.1.0/nuclei_3.1.0_linux_amd64.zip
unzip nuclei_3.1.0_linux_amd64.zip
sudo mv nuclei /usr/local/bin/
sudo chmod +x /usr/local/bin/nuclei
# Password tools
sudo apt install -y hydra john hashcat
# Exploit tools
sudo apt install -y exploitdb metasploit-framework
# Update searchsploit database
sudo searchsploit -u
```
#### On macOS:
```bash
# Using Homebrew
brew install nmap masscan
brew install gobuster sqlmap nikto
brew install john hashcat hydra
brew install ffuf nuclei
# Note: Some tools may not be available on macOS
```
### 3. Download Wordlists (Optional but Recommended)
```bash
# On Kali Linux
sudo apt install -y wordlists
sudo apt install -y seclists
# Extract rockyou.txt
sudo gunzip /usr/share/wordlists/rockyou.txt.gz
# On other systems, download manually:
mkdir -p ~/wordlists
cd ~/wordlists
# Download SecLists
git clone https://github.com/danielmiessler/SecLists.git
# Download rockyou
wget https://github.com/brannondorsey/naive-hashcat/releases/download/data/rockyou.txt
```
## Installing the Kali MCP Server
### Step 1: Navigate to Project Directory
```bash
cd /path/to/kali-mcp-server
```
### Step 2: Install Dependencies
```bash
npm install
```
This will install:
- `@modelcontextprotocol/sdk` - MCP protocol implementation
- `zod` - Runtime type validation
- TypeScript and type definitions
### Step 3: Build the Project
```bash
npm run build
```
This compiles TypeScript to JavaScript in the `dist/` directory.
### Step 4: Verify Installation
```bash
# Check build output
ls -la dist/
# Should see:
# - index.js
# - types.js
# - constants.js
# - utils/ directory
# - tools/ directory
# - schemas/ directory
```
## Testing the Server
### Method 1: Direct Execution
```bash
# Start the server
node dist/index.js
```
You should see:
```
⚠️ LEGAL NOTICE ⚠️
...
Kali MCP Server running on stdio
Registered 20 security tools
Ready for requests
```
Press Ctrl+C to stop.
### Method 2: MCP Inspector (Recommended)
The MCP Inspector provides a web UI for testing tools interactively.
```bash
# Install MCP Inspector globally (one-time)
npm install -g @modelcontextprotocol/inspector
# Launch inspector
npx @modelcontextprotocol/inspector node dist/index.js
# Or use the npm script
npm run inspector
```
This will open a web browser showing:
- List of all 20 tools
- Input forms for each tool
- Real-time execution and results
- Error messages and debugging info
### Method 3: Test Individual Tools
Create a test script `test-nmap.sh`:
```bash
#!/bin/bash
# Test nmap scan
echo '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "kali_network_nmap_scan",
"arguments": {
"target": "scanme.nmap.org",
"ports": "80,443",
"scan_type": "tcp_connect",
"timeout": 60
}
}
}' | node dist/index.js
```
Make it executable and run:
```bash
chmod +x test-nmap.sh
./test-nmap.sh
```
## Integration with Claude Desktop
### Step 1: Locate Configuration File
**macOS:**
```bash
~/Library/Application\ Support/Claude/claude_desktop_config.json
```
**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
**Linux:**
```bash
~/.config/Claude/claude_desktop_config.json
```
### Step 2: Add MCP Server Configuration
Edit the configuration file and add:
```json
{
"mcpServers": {
"kali-security": {
"command": "node",
"args": ["/absolute/path/to/kali-mcp-server/dist/index.js"]
}
}
}
```
**Important:** Use the absolute path to your `dist/index.js` file!
Find it with:
```bash
cd /path/to/kali-mcp-server
pwd
# Then append /dist/index.js
```
### Step 3: Restart Claude Desktop
Completely quit and restart Claude Desktop application.
### Step 4: Verify Integration
In Claude Desktop, you should see:
- A hammer icon (🔨) indicating MCP tools are available
- 20 tools listed when you click the icon
- Tools with names starting with `kali_`
### Step 5: Test with Claude
Try asking Claude:
```
Can you scan scanme.nmap.org for open ports 80 and 443?
```
Claude should use the `kali_network_nmap_scan` tool automatically.
## Troubleshooting
### "Command not found" errors
**Problem:** Tools like nmap, gobuster not found.
**Solution:**
```bash
# Check if tool is installed
which nmap
# Install missing tool
sudo apt install nmap
# Or set custom path in environment
export NMAP_PATH=/custom/path/to/nmap
```
### "Permission denied" errors
**Problem:** Some tools require root privileges.
**Solution:**
1. Use non-privileged alternatives (recommended):
```json
{
"scan_type": "tcp_connect" // Instead of "tcp_syn"
}
```
2. Grant specific capabilities (better than sudo):
```bash
sudo setcap cap_net_raw,cap_net_admin+eip /usr/bin/nmap
sudo setcap cap_net_raw,cap_net_admin+eip /usr/bin/masscan
sudo setcap cap_net_raw,cap_net_admin+eip /usr/bin/tcpdump
```
3. Run with sudo (not recommended):
```bash
sudo node dist/index.js
```
### "Module not found" errors
**Problem:** npm dependencies not installed.
**Solution:**
```bash
cd /path/to/kali-mcp-server
rm -rf node_modules package-lock.json
npm install
npm run build
```
### "Connection refused" in Claude Desktop
**Problem:** Claude can't connect to the MCP server.
**Solution:**
1. Check path in configuration is absolute
2. Verify build succeeded: `ls dist/index.js`
3. Test server manually: `node dist/index.js`
4. Check Claude Desktop logs (Help > Show Logs)
5. Restart Claude Desktop completely
### Timeout issues
**Problem:** Scans timing out before completion.
**Solution:**
Increase timeout in tool parameters:
```json
{
"target": "192.168.1.0/24",
"ports": "1-65535",
"timeout": 1800 // 30 minutes
}
```
Or adjust default timeouts in `src/constants.ts` and rebuild.
### Wordlist not found
**Problem:** "Invalid wordlist path" error.
**Solution:**
1. Check wordlist exists:
```bash
ls -la /usr/share/wordlists/dirb/common.txt
```
2. Use absolute path:
```json
{
"wordlist": "/usr/share/wordlists/dirb/common.txt"
}
```
3. Allowed wordlist directories (modify in `src/utils/validator.ts`):
- `/usr/share/wordlists/`
- `/usr/share/seclists/`
- `/usr/share/dirb/`
- `/usr/share/dirbuster/`
- `/tmp/`
- `/opt/`
## Advanced Configuration
### Custom Tool Paths
Set environment variables before starting:
```bash
export NMAP_PATH=/custom/nmap
export GOBUSTER_PATH=/custom/gobuster
export SQLMAP_PATH=/custom/sqlmap
node dist/index.js
```
Or modify `src/constants.ts` and rebuild.
### Rate Limiting
Adjust in `src/constants.ts`:
```typescript
export const DEFAULT_RATE_LIMIT = {
maxPerMinute: 20, // Increase from 10
maxPerHour: 200, // Increase from 100
};
```
Then rebuild: `npm run build`
### Output Limits
Modify in `src/constants.ts`:
```typescript
export const MAX_OUTPUT_SIZE = 50 * 1024 * 1024; // 50MB instead of 10MB
```
### Timeouts
Modify tool-specific timeouts in `src/constants.ts`:
```typescript
export const TOOL_TIMEOUTS: Record<string, number> = {
nmap: 1200000, // 20 minutes instead of 10
gobuster: 1200000, // 20 minutes instead of 10
// ...
};
```
## Updating the Server
```bash
cd /path/to/kali-mcp-server
# Pull latest changes (if using git)
git pull
# Reinstall dependencies
npm install
# Rebuild
npm run build
# Restart (if running as service)
# Or restart Claude Desktop
```
## Security Best Practices
1. **Never run as root** unless absolutely necessary
2. **Use capability grants** instead of sudo for network tools
3. **Keep tools updated**: `sudo apt update && sudo apt upgrade`
4. **Review scan targets** before execution
5. **Monitor logs** in stderr output
6. **Limit rate** to prevent accidental DoS
7. **Use in controlled environments** only
## Getting Help
- Check logs: Server outputs to stderr
- Enable verbose mode in tools
- Test tools manually: `nmap --help`
- Review MCP Inspector output
- Check Claude Desktop logs
## Next Steps
1. ✅ Install prerequisites
2. ✅ Install dependencies: `npm install`
3. ✅ Build project: `npm run build`
4. ✅ Test with MCP Inspector: `npm run inspector`
5. ✅ Configure Claude Desktop
6. ✅ Start testing tools
Congratulations! Your Kali MCP Server is ready for authorized security testing.
