# Installation Guide
Comprehensive setup guide for the Pentest MCP Server across all platforms.
---
## Prerequisites
### **Client System (Where you run the MCP server):**
- **Python 3.10+** (Windows, macOS, Linux)
- **Claude Desktop, Windsurf, Cursor, 5ire, WARP or any other mcp client**
### **Target System (Pentesting distribution):**
- **Linux pentesting distribution** (Kali, Parrot, BackBox, etc.)
- **SSH access** to target system (password or key-based)
- **tmux** installed on target system
- **User account** (not root - for security)
---
## Quick Install (5 minutes)
### 1. Clone Repository
```bash
git clone https://github.com/LayeSec006/pentest-mcp-server.git
cd pentest-mcp-server
```
### 2. Install Package
```bash
# Install the package in development mode
pip install -e .
```
**Note:** The `-e` flag installs the package in "editable" mode, which means changes to the source code are immediately reflected without reinstalling.
### 3. Configure Environment
```bash
cp .env.example .env
```
Edit `.env` with your target system details:
```env
TARGET_HOST=192.168.1.100
TARGET_PORT=22
TARGET_USER=kali
TARGET_PASSWORD=your_password
```
### 4. Prepare Target System
SSH into your target system and install tmux:
```bash
ssh kali@192.168.1.100
# For Debian/Ubuntu/Kali/Parrot:
sudo apt update && sudo apt install tmux
# For Arch/BlackArch:
sudo pacman -S tmux
# For RHEL/CentOS/Fedora:
sudo yum install tmux
# OR for newer versions:
sudo dnf install tmux
# For Alpine Linux:
sudo apk add tmux
exit
```
### 5. Test Installation
```bash
python -m pytest tests/ -v
```
**Done!** ✅
---
## IDE Integration
### Claude Desktop Integration
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"pentest-mcp": {
"command": "python",
"args": ["-m", "pentest_mcp_server"],
"env": {
"TARGET_HOST": "192.168.1.100",
"TARGET_USER": "kali",
"TARGET_PASSWORD": "your_password"
}
}
}
}
```
### Windsurf Integration
Add to your Windsurf settings:
```json
{
"mcpServers": {
"pentest-mcp": {
"command": "python",
"args": ["-m", "pentest_mcp_server"],
"env": {
"TARGET_HOST": "192.168.1.100",
"TARGET_USER": "kali",
"TARGET_PASSWORD": "your_password"
}
}
}
}
```
### Cursor Integration
Add to your Cursor settings:
```json
{
"mcpServers": {
"pentest-mcp": {
"command": "python",
"args": ["-m", "pentest_mcp_server"],
"env": {
"TARGET_HOST": "192.168.1.100",
"TARGET_USER": "kali",
"TARGET_PASSWORD": "your_password"
}
}
}
}
```
### 5ire Integration
Add to your 5ire configuration:
```json
{
"mcpServers": {
"pentest-mcp": {
"command": "python",
"args": ["-m", "pentest_mcp_server"],
"env": {
"TARGET_HOST": "192.168.1.100",
"TARGET_USER": "kali",
"TARGET_PASSWORD": "your_password"
}
}
}
}
```
### Warp AI Integration
Add to your Warp configuration:
**Configuration File:** `~/.warp/config.toml`
```toml
[[mcp_servers]]
name = "pentest-mcp"
command = "python"
args = ["-m", "pentest_mcp_server"]
[mcp_servers.env]
TARGET_HOST = "192.168.1.100"
TARGET_USER = "kali"
TARGET_PASSWORD = "your_password"
```
**Restart Warp after configuration.**
**Restart your IDE after configuration.**
---
## Verify Installation
### Test Configuration
```bash
python -c "from pentest_mcp_server.config import Config; c = Config(); print('Config loaded:', c.TARGET_HOST)"
```
### Test MCP Server Import
```bash
python -c "from pentest_mcp_server import main; print('MCP server imported successfully')"
```
### Test with Environment Variables
```bash
python -c "import os; os.environ['TARGET_HOST']='192.168.1.100'; os.environ['TARGET_USER']='kali'; os.environ['TARGET_PASSWORD']='test'; from pentest_mcp_server.config import Config; c = Config(); print('Config with env vars:', c.TARGET_HOST)"
```
### Run Example
```bash
cd examples
python basic_scan.py 127.0.0.1
```
---
## Troubleshooting
### Connection Refused
```
Error: Connection failed: [Errno 111] Connection refused
```
**Fix:**
```bash
# On Kali
service ssh status
service ssh start
```
### Tmux Not Found
```
Error: tmux is not installed on target system
```
**Fix:**
```bash
# On Kali
apt update && apt install tmux
```
### Permission Denied
```
Error: Permission denied (publickey,password)
```
**Fix:**
- Verify credentials in `.env`
- Enable password auth in `/etc/ssh/sshd_config` on Kali:
```
PasswordAuthentication yes
```
- Restart SSH: `service ssh restart`
### Package Not Found
```
ModuleNotFoundError: No module named 'pentest_mcp_server'
```
**Fix:**
```bash
# Make sure you're in the project directory
cd pentest_mcp_server
# Install in editable mode
pip install -e .
# Verify installation
python -c "import pentest_mcp_server; print('Package installed successfully')"
```
---
## Next Steps
1. **Try Examples:** `cd examples && python basic_scan.py <target>`
2. **Read Docs:** See `README.md` for full documentation
3. **Run Tests:** `python -m pytest tests/ -v` to verify everything works
---
**Installation complete!** Start pentesting! 🚀
