{"id":47220166,"url":"https://github.com/LayeSec006/pentest-mcp-server","last_synced_at":"2026-03-27T23:01:12.438Z","repository":{"id":343456695,"uuid":"1072834623","full_name":"LayeSec006/pentest-mcp-server","owner":"LayeSec006","description":"MCP server for penetration testing","archived":false,"fork":false,"pushed_at":"2025-10-12T09:56:28.000Z","size":576,"stargazers_count":16,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-10T18:52:55.242Z","etag":null,"topics":["asyncio","automation","kali","kali-linux","mcp","model-context-protocol","parrot","parrot-os","parrotsec","penetration-testing","penetration-testing-tools","pentesting","security","ssh","tmux"],"latest_commit_sha":null,"homepage":"https://github.com/LayeSec006/pentest-mcp-server","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LayeSec006.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-09T09:22:53.000Z","updated_at":"2026-03-09T16:04:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LayeSec006/pentest-mcp-server","commit_stats":null,"previous_names":["layesec006/pentest-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/LayeSec006/pentest-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LayeSec006%2Fpentest-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LayeSec006%2Fpentest-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LayeSec006%2Fpentest-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LayeSec006%2Fpentest-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LayeSec006","download_url":"https://codeload.github.com/LayeSec006/pentest-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LayeSec006%2Fpentest-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31065013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T22:49:25.097Z","status":"ssl_error","status_checked_at":"2026-03-27T22:49:22.599Z","response_time":164,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","automation","kali","kali-linux","mcp","model-context-protocol","parrot","parrot-os","parrotsec","penetration-testing","penetration-testing-tools","pentesting","security","ssh","tmux"],"created_at":"2026-03-13T18:00:36.704Z","updated_at":"2026-03-27T23:01:12.418Z","avatar_url":"https://github.com/LayeSec006.png","language":"Python","funding_links":[],"categories":["automation"],"sub_categories":[],"readme":"# Pentest MCP Server\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](tests/)\n\nA **production-ready** Model Context Protocol (MCP) server that enables AI agents to perform autonomous penetration testing on **ANY Linux distribution** via SSH. Built with persistent tmux sessions, intelligent triggers, auto-reconnection, and comprehensive resource management.\n\n\u003e **🚀 Key Differentiator:** Unlike other MCP servers that run commands independently, this server provides **persistent session management** with tmux, enabling complex interactive workflows and long-running operations.\n\n## 📋 Table of Contents\n\n- [👤 Connect](#-connect)\n- [🖼️ Screenshots](#️-screenshots)\n- [🎯 Core Capabilities](#-core-capabilities)\n- [🎯 Key Features](#-key-features)\n- [🎯 Real-World Impact](#-real-world-impact)\n- [🏗️ Architecture](#️-architecture)\n- [🚀 Quick Start](#-quick-start)\n  - [Installation (5 minutes)](#installation-5-minutes)\n  - [Configuration](#configuration)\n  - [AI Platform Integration](#ai-platform-integration)\n- [🔧 Quick Setup](#-quick-setup)\n- [🚀 Advanced Capabilities](#-advanced-capabilities)\n- [🛠️ MCP Tools](#️-mcp-tools)\n- [💡 Usage Examples](#-usage-examples)\n- [🔒 Security Features](#-security-features)\n- [🧪 Testing](#-testing)\n- [📊 Monitoring \u0026 Debugging](#-monitoring--debugging)\n- [🔧 Advanced Configuration](#-advanced-configuration)\n- [🐛 Troubleshooting](#-troubleshooting)\n- [🤝 Contributing](#-contributing)\n- [📝 License](#-license)\n- [⚠️ Legal Disclaimer](#️-legal-disclaimer)\n- [🙏 Acknowledgments](#-acknowledgments)\n\n## 👤 Connect\n\n🎥 **Video Tutorial:** [Watch the complete walkthrough on YouTube](https://youtu.be/jDGuZIOjksc)\n\nLinkedIn: [Abdallah Ndiaye](https://www.linkedin.com/in/abdallah-ndiaye-a3b98b380)\n\n## 🖼️ Screenshots\n\n![Screenshot 1](assets/Screenshot%201.png)\n![Screenshot 2](assets/Screenshot%202.png)\n![Screenshot 3](assets/Screenshot%203.png)\n![Screenshot 4](assets/Screenshot%204.png)\n\n## 🎯 **Core Capabilities**\n\nThis MCP server provides AI agents with **persistent session control** over ANY Linux distribution through SSH, enabling:\n\n- **🌍 Universal Compatibility**: Works with Kali Linux, Parrot Security, BackBox, and ANY Linux distribution\n- **🔓 Zero Tool Limitations**: Run ANY tool installed on the target system - no restrictions\n- **🔄 Persistent Sessions**: Tmux-based sessions that survive disconnections and crashes\n- **🤖 Intelligent Automation**: AI suspension/resumption based on output patterns and triggers\n- **⚡ Auto-Reconnection**: Automatic SSH reconnection with exponential backoff\n- **📊 Resource Management**: Smart limits on concurrent heavy operations\n- **🎯 Interactive Tools**: Full support for msfconsole, mysql, reverse shells, and complex workflows\n- **🛡️ Session Recovery**: Recover all sessions after crashes or network issues\n\n## 🎯 **Key Features**\n\n### **Our Core Advantages:**\n- **🔄 Session Persistence**: Sessions survive disconnections and crashes\n- **🎯 Interactive Tool Support**: Handle msfconsole, reverse shells, complex workflows\n- **🤖 Intelligent Automation**: AI suspension/resumption with smart triggers\n- **⚡ Auto-Reconnection**: Automatic recovery from network issues\n- **📊 Resource Management**: Smart limits and system monitoring\n- **🌍 Universal Compatibility**: Works with any Linux distribution\n\n\u003e **💡 The Advantage:** Our server provides **persistent session management** that enables complex, multi-step pentesting workflows with full interactive tool support.\n\n## 🎯 **Real-World Impact**\n\n### **What This Enables:**\n- **Complex Workflows**: Multi-step pentesting operations that span hours\n- **Interactive Tools**: Full Metasploit automation, reverse shell management\n- **Session Persistence**: Long-running scans that survive network issues\n- **Resource Management**: Smart limits on concurrent operations\n- **Universal Deployment**: Works on any Linux distribution\n\n### **Use Cases:**\n- **Red Team Operations**: Automated reconnaissance and exploitation\n- **CTF Challenges**: Complex multi-step problem solving\n- **Security Research**: Long-running vulnerability assessments\n- **AI-Assisted Pentesting**: Intelligent automation of repetitive tasks\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────┐\n│   AI Agent          │\n│   (Claude/ChatGPT)  │\n└──────────┬──────────┘\n           │ MCP Protocol\n           ▼\n┌─────────────────────┐\n│   MCP Server        │\n│   (Python)          │\n│                     │\n│  ┌───────────────┐  │\n│  │Session Manager│  │\n│  │Auto-Reconnect │  │\n│  │Resource Mgmt  │  │\n│  └───────────────┘  │\n└──────────┬──────────┘\n           │ SSH + PTY\n           ▼\n┌─────────────────────┐\n│   Pentest System    │\n│   (Kali/Parrot/etc) │\n│                     │\n│  ┌───────────────┐  │\n│  │    tmux       │  │\n│  │  ┌─────────┐  │  │\n│  │  │Session 1│  │  │\n│  │  │Session 2│  │  │\n│  │  │Session N│  │  │\n│  │  └─────────┘  │  │\n│  └───────────────┘  │\n└─────────────────────┘\n```\n\n## 🚀 Quick Start\n\n### Installation (5 minutes)\n\n```bash\n# 1. Clone repository\ngit clone https://github.com/LayeSec006/pentest-mcp-server.git\ncd pentest-mcp-server\n\n# 2. Install package\npip install -e .\n\n# 3. Configure\ncp .env.example .env\n# Edit .env with your pentesting os details\n\n# 4. Install tmux on target system\nssh kali@\u003cTARGET_HOST\u003e\n\n# For Debian/Ubuntu/Kali/Parrot:\nsudo apt update \u0026\u0026 sudo apt install tmux\n\n# For Arch/BlackArch:\nsudo pacman -S tmux\n\n# For RHEL/CentOS/Fedora:\nsudo yum install tmux\n# OR for newer versions:\nsudo dnf install tmux\n\n# For Alpine Linux:\nsudo apk add tmux\n\nexit\n\n# 5. Test\npython -m pytest tests/ -v\n```\n\n### Configuration\n\nCreate a `.env` file with your target system details:\n\n```env\n# SSH Connection\nTARGET_HOST=192.168.1.100\nTARGET_PORT=22\nTARGET_USER=kali\nTARGET_PASSWORD=your_password\n# OR use SSH key instead\n# TARGET_SSH_KEY=/path/to/private/key\n\n# Resource Limits\nMAX_SESSIONS=20\nMAX_HEAVY_TASKS=3\n\n# Monitoring\nPOLL_INTERVAL=1.0\nDEFAULT_TIMEOUT=300\n```\n\n## 🤖 AI Platform Integration\n\n### Claude Desktop Integration\n\nAdd to your Claude Desktop configuration:\n\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`  \n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Linux:** `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"pentest-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"pentest_mcp_server\"],\n      \"env\": {\n        \"TARGET_HOST\": \"192.168.1.100\",\n        \"TARGET_USER\": \"kali\", \n        \"TARGET_PASSWORD\": \"your_password\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf Integration\n\nAdd to your Windsurf settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"pentest-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"pentest_mcp_server\"],\n      \"env\": {\n        \"TARGET_HOST\": \"192.168.1.100\",\n        \"TARGET_USER\": \"kali\",\n        \"TARGET_PASSWORD\": \"your_password\"\n      }\n    }\n  }\n}\n```\n\n### Cursor Integration\n\nAdd to your Cursor settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"pentest-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"pentest_mcp_server\"],\n      \"env\": {\n        \"TARGET_HOST\": \"192.168.1.100\",\n        \"TARGET_USER\": \"kali\",\n        \"TARGET_PASSWORD\": \"your_password\"\n      }\n    }\n  }\n}\n```\n\n### 5ire Integration\n\nIn 5ire:\n1. Click on **Tools** in the main interface\n2. Click the **Local** button\n3. Fill out the \"Edit tool (Local Server)\" form:\n   - **Tool Key:** `pentest-mcp`\n   - **Name:** `Pentest MCP` (optional)\n   - **Description:** `AI-powered penetration testing server` (optional)\n   - **Approval Policy:** Select `Always` (recommended)\n   - **Command:** `python -m pentest_mcp_server`\n   - **Environment Variables:**\n     - `TARGET_HOST` = `192.168.1.100`\n     - `TARGET_USER` = `kali` \n     - `TARGET_PASSWORD` = `your_password`\n4. Review the **Config Preview** to ensure it's correct\n5. Click **Save**\n6. **Enable the tool:** Hover over the `pentest-mcp` entry in the Tools list and click the **toggle button** that appears on the right to enable it\n```\n\n### Warp AI Integration\n\nIn Warp terminal:\n1. Go to **Settings** (⌘ + ,)\n2. Click on **AI** in the sidebar\n3. Scroll down to find **Manage MCP**\n4. Click **Add MCP**\n5. Paste this JSON configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"pentest-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"pentest_mcp_server\"],\n      \"env\": {\n        \"TARGET_HOST\": \"192.168.1.100\",\n        \"TARGET_USER\": \"kali\",\n        \"TARGET_PASSWORD\": \"your_password\"\n      }\n    }\n  }\n}\n```\n\n6. Click **Save**\n7. Restart Warp\n\n## 🔧 Quick Setup\n\n### Setup Steps\n\n```bash\n# 1. Clone and install\ngit clone https://github.com/LayeSec006/pentest-mcp-server.git\ncd pentest-mcp-server\npip install -e .\n\n# 2. Configure\ncp .env.example .env\n# Edit .env with your target system details\n\n# 3. Test configuration\npython -c \"from pentest_mcp_server.config import Config; c = Config(); print('Config loaded:', c.TARGET_HOST)\"\n```\n\n## 🚀 Advanced Capabilities\n\n### 🎯 Interactive Tool Support\n\nStart and interact with complex tools like Metasploit Framework:\n\n```json\n{\n  \"tool\": \"execute\",\n  \"args\": {\n    \"session_id\": \"msf_session\",\n    \"command\": \"msfconsole -q\"\n  }\n}\n```\n\nInteract with the running tool:\n\n```json\n{\n  \"tool\": \"send_input\",\n  \"args\": {\n    \"session_id\": \"msf_session\",\n    \"input\": \"use exploit/multi/handler\"\n  }\n}\n```\n\n### 🔄 Reverse Shell Management\n\nHandle incoming reverse shells seamlessly:\n\n```json\n{\n  \"tool\": \"execute\",\n  \"args\": {\n    \"session_id\": \"reverse_shell\",\n    \"command\": \"nc -lvp 4444\"\n  }\n}\n```\n\nInteract with connected shells:\n\n```json\n{\n  \"tool\": \"send_input\",\n  \"args\": {\n    \"session_id\": \"reverse_shell\",\n    \"input\": \"whoami\"\n  }\n}\n```\n\n### 📊 Complex Workflow Automation\n\nSupport for multi-step pentesting workflows:\n\n1. **Network reconnaissance** (nmap, masscan)\n2. **Web application scanning** (gobuster, nikto, dirb)\n3. **Vulnerability exploitation** (metasploit, custom exploits)\n4. **Post-exploitation** (meterpreter, privilege escalation)\n5. **Data exfiltration** (file operations, tunneling)\n\n### 🛡️ Session Persistence \u0026 Recovery\n\nSessions survive network interruptions and crashes:\n\n```json\n{\n  \"tool\": \"recover_sessions\",\n  \"args\": {}\n}\n```\n\n**Key Benefits:**\n- Sessions continue running even if SSH connection drops\n- Automatic reconnection with exponential backoff\n- State preservation across network issues\n- Full recovery of interactive sessions\n\n## 🛠️ MCP Tools\n\n### Session Management\n\n| Tool | Description | Purpose |\n|------|-------------|----------|\n| `create_session` | Create new persistent tmux session | Start isolated workspace for pentesting tasks |\n| `list_sessions` | List all active sessions | Monitor running operations |\n| `kill_session` | Terminate specific session | Clean up completed tasks |\n\n#### `create_session`\nCreate a new persistent tmux session for isolated pentesting operations.\n\n**Parameters:**\n```json\n{\n  \"session_id\": \"scan_network\",\n  \"shell\": \"bash\"\n}\n```\n\n#### `list_sessions` \nList all active tmux sessions and their status.\n\n**Parameters:**\n```json\n{}\n```\n\n#### `kill_session`\nTerminate a specific session and clean up resources.\n\n**Parameters:**\n```json\n{\n  \"session_id\": \"scan_network\"\n}\n```\n\n### Command Execution\n\n| Tool | Description | Purpose |\n|------|-------------|----------|\n| `execute` | Execute commands in persistent sessions | Run pentesting tools and scripts |\n| `read_output` | Get current output from session | Monitor command progress and results |\n| `send_input` | Send input to interactive tools | Control interactive applications |\n\n#### `execute`\nExecute commands in persistent sessions.\n\n```json\n{\n  \"session_id\": \"scan_network\",\n  \"command\": \"nmap -sV 192.168.1.0/24\",\n  \"background\": false\n}\n```\n\n#### `read_output`\nGet current output from a session.\n\n```json\n{\n  \"session_id\": \"scan_network\",\n  \"lines\": 50\n}\n```\n\n#### `send_input`\nSend input to interactive tools.\n\n```json\n{\n  \"session_id\": \"msf_session\",\n  \"input\": \"use exploit/multi/handler\",\n  \"press_enter\": true\n}\n```\n\n### System Management\n\n#### `get_system_status`\nGet system resource usage and session status.\n\n```json\n{}\n```\n\n#### `recover_sessions`\nRecover orphaned sessions after reconnection.\n\n```json\n{}\n```\n\n### File Operations\n\n#### `upload_file`\nUpload files to your system via SFTP.\n\n```json\n{\n  \"local_path\": \"/path/to/local/file\",\n  \"remote_path\": \"/tmp/uploaded_file\"\n}\n```\n\n#### `download_file`\nDownload files from your system via SFTP.\n\n```json\n{\n  \"remote_path\": \"/tmp/scan_results.xml\",\n  \"local_path\": \"/path/to/local/results.xml\"\n}\n```\n\n### Tool Output Parsing\n\n#### `parse_tool_output`\nParse common pentest tool outputs (nmap XML, JSON, etc.).\n\n```json\n{\n  \"tool\": \"nmap\",\n  \"file_path\": \"/tmp/scan.xml\",\n  \"format\": \"xml\"\n}\n```\n\n## 💡 Usage Examples\n\n### Basic Network Scan\n\n```\nAI: I need to scan the network 192.168.1.0/24\n\nTool: create_session\nArgs: {\"session_id\": \"network_scan\"}\n\nTool: execute  \nArgs: {\n  \"session_id\": \"network_scan\",\n  \"command\": \"nmap -sV 192.168.1.0/24 -oX /tmp/scan.xml\"\n}\n\nTool: read_output\nArgs: {\"session_id\": \"network_scan\"}\n```\n\n### Interactive Metasploit Usage\n\n```\nAI: Let me start Metasploit and set up a handler\n\nTool: create_session\nArgs: {\"session_id\": \"metasploit\"}\n\nTool: execute\nArgs: {\n  \"session_id\": \"metasploit\", \n  \"command\": \"msfconsole -q\"\n}\n\nTool: send_input\nArgs: {\n  \"session_id\": \"metasploit\",\n  \"input\": \"use exploit/multi/handler\"\n}\n\nTool: send_input  \nArgs: {\n  \"session_id\": \"metasploit\",\n  \"input\": \"set PAYLOAD linux/x64/meterpreter/reverse_tcp\"\n}\n\nTool: send_input\nArgs: {\n  \"session_id\": \"metasploit\", \n  \"input\": \"exploit\"\n}\n```\n\n### Parallel Operations\n\n```\nAI: I'll run multiple scans in parallel\n\nTool: create_session\nArgs: {\"session_id\": \"nmap_scan\"}\n\nTool: create_session \nArgs: {\"session_id\": \"gobuster_scan\"}\n\nTool: execute\nArgs: {\n  \"session_id\": \"nmap_scan\",\n  \"command\": \"nmap -p- 192.168.1.5\",\n  \"background\": true\n}\n\nTool: execute\nArgs: {\n  \"session_id\": \"gobuster_scan\", \n  \"command\": \"gobuster dir -u http://192.168.1.5 -w /usr/share/wordlists/dirb/common.txt\",\n  \"background\": true\n}\n```\n\n## 🔒 Security Features\n\n### Command Filtering (Optional)\nThe server can optionally block dangerous commands:\n\n- `rm -rf /` - Recursive delete from root\n- `dd if=...of=/dev/sd*` - Disk wiping commands  \n- `mkfs` - Filesystem formatting\n- Fork bombs and other destructive patterns\n\n## 🧪 Testing\n\nRun the test suite:\n\n```bash\n# Install test dependencies\npip install pytest pytest-asyncio pytest-mock\n\n# Run tests\npython -m pytest tests/ -v\n\n# Run with coverage\npython -m pytest tests/ --cov=pentest_mcp_server --cov-report=html\n```\n\n### Test Categories\n\n- **Unit Tests**: Individual component testing\n- **Integration Tests**: End-to-end workflow testing  \n- **Connection Tests**: SSH and reconnection scenarios\n- **Session Tests**: Tmux session management\n\n## 📊 Monitoring \u0026 Debugging\n\n### Logging\nThe server provides detailed logging:\n\n```python\nimport logging\nlogging.basicConfig(level=logging.INFO)\n```\n\nLog levels:\n- `INFO`: Connection status, session creation/destruction\n- `WARNING`: Reconnection attempts, blocked commands\n- `ERROR`: Connection failures, command errors\n- `DEBUG`: Detailed protocol messages\n\n### System Status\nUse the `get_system_status` tool to monitor:\n\n- CPU and memory usage\n- Active session count  \n- Connection health\n- Recent command history\n\n### Session Recovery\nAfter crashes or network issues:\n\n```\nTool: recover_sessions\nArgs: {}\n\nResponse: {\n  \"status\": \"success\",\n  \"recovered_sessions\": [\n    {\n      \"session_id\": \"network_scan\",\n      \"age_seconds\": 1800,\n      \"last_output\": \"...Nmap scan report...\"\n    }\n  ]\n}\n```\n\n## 🔧 Advanced Configuration\n\n### Resource Management\n\n```env\n# Limit concurrent heavy operations\nMAX_HEAVY_TASKS=3\n\n# Heavy commands that count against the limit\nHEAVY_COMMANDS=nmap,masscan,hydra,john,hashcat,sqlmap\n```\n\n### Connection Tuning\n\n```env\n# Reconnection settings\nMAX_RECONNECT_ATTEMPTS=5\nRECONNECT_DELAY_BASE=2  # Exponential backoff base\n\n# Health check interval  \nPOLL_INTERVAL=1.0\n\n# Default command timeout\nDEFAULT_TIMEOUT=300\n```\n\n### Tmux Customization\n\n```env\n# Custom tmux socket name\nTMUX_SOCKET_NAME=mcp-pentest\n\n# Session persistence location\nTMUX_SESSION_PATH=/tmp/mcp-sessions\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Connection Refused**\n```\nError: Connection failed: [Errno 111] Connection refused\n```\n- Verify SSH is running on your system: `service ssh status`\n- Check firewall rules: `ufw status`\n- Verify host/port in configuration\n\n**Authentication Failed** \n```\nError: Permission denied (publickey,password)\n```\n- Verify username/password are correct\n- Check SSH key permissions (600)\n- Enable password auth: `PasswordAuthentication yes` in `/etc/ssh/sshd_config`\n\n**Tmux Not Found**\n```\nError: tmux is not installed on target system\n```\n- Install tmux on your distro: `apt update \u0026\u0026 apt install tmux`\n\n**Session Lost**\n```\nError: Session 'scan_network' does not exist\n```\n- Use `recover_sessions` tool to find orphaned sessions\n- Check if the system rebooted (sessions don't survive reboot)\n\n### Debug Mode\n\nEnable verbose logging:\n\n```python\nimport logging\nlogging.getLogger('pentest_mcp_server').setLevel(logging.DEBUG)\nlogging.getLogger('asyncssh').setLevel(logging.DEBUG)\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)  \n3. Run tests (`python -m pytest tests/`)\n4. Commit changes (`git commit -m 'Add amazing feature'`)\n5. Push to branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n### Development Setup\n\n```bash\ngit clone \u003cyour-fork\u003e\ncd pentest_mcp_server\npip install -e .\npip install pytest pytest-asyncio pytest-mock\n```\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## ⚠️ Legal Disclaimer\n\nThis tool is intended for authorized security testing and educational purposes only. Users are responsible for ensuring they have proper authorization before using this tool against any systems. The developers are not responsible for any misuse or damage caused by this tool.\n\n## 🙏 Acknowledgments  \n\n- Based on [t-suganuma/ssh-connect-mcp-server](https://github.com/t-suganuma/ssh-connect-mcp-server)\n- Built with [asyncssh](https://asyncssh.readthedocs.io/) for superior SSH handling\n- Uses [tmux](https://github.com/tmux/tmux) for persistent sessions\n- Implements [Model Context Protocol](https://modelcontextprotocol.io/) specification\n\n---\n\n**Happy Pentesting! 🔒🔓**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLayeSec006%2Fpentest-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLayeSec006%2Fpentest-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLayeSec006%2Fpentest-mcp-server/lists"}