# 🔧 Troubleshooting Guide
## Common Issues and Solutions
### 1. **MCP Server Not Starting**
**Error:** `Either TARGET_PASSWORD or TARGET_SSH_KEY must be provided`
**Solution:**
1. Create a `.env` file in your project root:
```env
TARGET_HOST=192.168.1.100
TARGET_PORT=22
TARGET_USER=kali
TARGET_PASSWORD=your_password
```
2. Or set environment variables:
```bash
export TARGET_HOST=192.168.1.100
export TARGET_USER=kali
export TARGET_PASSWORD=your_password
```
### 2. **Configuration Not Loading**
**Error:** `AttributeError: 'Config' object has no attribute 'TARGET_HOST'`
**Solution:**
1. Make sure you're using the correct variable names in your `.env` file:
- `TARGET_HOST`
- `TARGET_USER`
- `TARGET_PASSWORD`
2. Reinstall the package:
```bash
pip install -e .
```
### 3. **IDE Integration Issues**
**Claude Desktop:**
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
**Windsurf/Cursor:**
- Check your IDE's MCP settings
- Ensure the command path is correct: `python -m pentest_mcp_server`
### 4. **SSH Connection Issues**
**Error:** `Connection refused`
**Solution:**
1. Check if SSH is running on target system:
```bash
ssh kali@192.168.1.100
```
2. Enable SSH on target system:
```bash
# On Kali/Parrot/BackBox:
sudo systemctl start ssh
sudo systemctl enable ssh
# On Arch/BlackArch:
sudo systemctl start sshd
sudo systemctl enable sshd
```
### 5. **Tmux Not Found**
**Error:** `tmux is not installed on target system`
**Solution:**
Install tmux on target system:
```bash
# Kali/Parrot/BackBox:
sudo apt update && sudo apt install tmux
# Arch/BlackArch:
sudo pacman -S tmux
# RHEL/CentOS/Fedora:
sudo yum install tmux
# OR for newer versions:
sudo dnf install tmux
# Alpine Linux:
sudo apk add tmux
```
### 6. **Permission Denied**
**Error:** `Permission denied (publickey,password)`
**Solution:**
1. Verify credentials in `.env`
2. Enable password auth in `/etc/ssh/sshd_config` on target:
```
PasswordAuthentication yes
```
3. Restart SSH: `sudo systemctl restart ssh`
### 7. **Package Not Found**
**Error:** `ModuleNotFoundError: No module named 'pentest_mcp_server'`
**Solution:**
1. Make sure you're in the project directory:
```bash
cd pentest-mcp-server
```
2. Install in editable mode:
```bash
pip install -e .
```
3. Verify installation:
```bash
python -c "import pentest_mcp_server; print('Package installed successfully')"
```
### 8. **Environment Variables Not Loading**
**Error:** Configuration shows default values
**Solution:**
1. Check if `.env` file exists in project root
2. Verify file encoding (should be UTF-8)
3. Check file permissions
4. Try setting environment variables directly:
```bash
export TARGET_HOST=192.168.1.100
export TARGET_USER=kali
export TARGET_PASSWORD=your_password
```
### 9. **MCP Server Name Issues**
**Error:** MCP server not recognized by IDE
**Solution:**
1. Use the correct server name: `pentest-mcp`
2. Check your IDE 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"
}
}
}
}
```
### 10. **Testing the Installation**
**Quick Test:**
```bash
# Test configuration
python -c "from pentest_mcp_server.config import Config; c = Config(); print('Config loaded:', c.TARGET_HOST)"
# Test MCP server import
python -c "from pentest_mcp_server import main; print('MCP server imported successfully')"
# Test with environment variables
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)"
```
## Still Having Issues?
1. **Check the logs** for detailed error messages
2. **Verify your target system** is accessible via SSH
3. **Test SSH connection** manually first
4. **Check IDE logs** for MCP connection errors
5. **Ensure all dependencies** are installed
## Getting Help
If you're still having issues:
1. Check the project's GitHub issues
2. Verify your configuration matches the examples
3. Test with a simple SSH connection first
4. Ensure your target system has tmux installed
