🔧 Safe Terminal MCP Server\n\nA secure Model Context Protocol (MCP) server that provides safe terminal command execution for AI assistants like Claude Desktop. Built with TypeScript and comprehensive security controls.\n\n## 🛡️ Security-First Design\n\nThis server implements defense-in-depth security to safely expose terminal capabilities to AI assistants:\n\n- ✅ Command Whitelisting: Only pre-approved, safe commands allowed\n- ✅ Input Sanitization: Multiple layers of injection prevention\n- ✅ Resource Limits: Timeouts, output size limits, rate limiting\n- ✅ Process Isolation: Secure execution environment\n- ✅ Comprehensive Auditing: Full security event logging\n- ✅ Directory Restrictions: Configurable path limitations\n- ✅ No Destructive Operations: Read-only and safe commands only\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 18+ \n- TypeScript\n- Git (optional, for git commands)\n- npm (optional, for npm commands)\n\n### Installation\n\nbash\n# Clone the repository\ngit clone https://github.com/luiscnext/mcp-safe-terminal-server.git\ncd mcp-safe-terminal-server\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Start the server\nnpm start\n\n\n### Configuration\n\nCopy .env.example to .env and customize:\n\nbash\ncp .env.example .env\n# Edit .env with your preferred settings\n\n\n## 🔌 Claude Desktop Integration\n\nTo use this server with Claude Desktop, add it to your MCP configuration:\n\njson\n{\n \"mcpServers\": {\n \"safe-terminal\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-safe-terminal-server/dist/index.js\"],\n \"env\": {\n \"DEFAULT_WORKING_DIR\": \"/path/to/your/workspace\",\n \"ALLOWED_DIRECTORIES\": \"/path/to/your/workspace,/tmp/safe\",\n \"LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n\n\nSee docs/CLAUDE_INTEGRATION.md for detailed setup instructions.\n\n## 🛠️ Available Commands\n\nThe server provides access to carefully vetted commands organized by category:\n\n### System Information (Read-Only)\n- ls - List directory contents\n- pwd - Show current directory\n- whoami - Display current user\n- date - Show current date/time\n- uname - System information\n- df - Disk usage\n- free - Memory usage\n- uptime - System uptime\n\n### File Operations (Read-Only)\n- cat - Display file contents (safe files only)\n- head - Show first lines of files\n- tail - Show last lines of files\n- wc - Count lines/words/characters\n- find - Find files (restricted paths)\n\n### Git Operations (Read-Only)\n- git status - Repository status\n- git log - Commit history\n- git branch - List branches\n- git diff - Show differences\n- git show - Show commit details\n- git remote - List remotes\n\n### NPM Operations (Read-Only)\n- npm list - List installed packages\n- npm outdated - Check for outdated packages\n- npm view - View package information\n- npm config - View configuration\n\n## 🔒 Security Features\n\n### Multi-Layer Input Validation\n\n1. Command Whitelisting: Only explicitly approved commands\n2. Argument Sanitization: Strip dangerous characters and patterns\n3. Injection Prevention: Block shell metacharacters and injection patterns\n4. Path Validation: Restrict file access to allowed directories\n5. Length Limits: Prevent buffer overflow attacks\n\n### Execution Environment\n\n- Process Isolation: Commands run in controlled environment\n- Resource Limits: CPU time, memory, and output size restrictions\n- Clean Environment: Sanitized environment variables\n- Timeout Protection: Automatic process termination for long-running commands\n- No Shell Access: Direct process spawning without shell interpretation\n\n### Monitoring & Auditing\n\n- Comprehensive Logging: All commands and security events logged\n- Security Event Detection: Suspicious activity monitoring\n- Rate Limiting: Prevent abuse with configurable limits\n- Audit Trail: Detailed logs for compliance and incident response\n\n### Blocked Operations\n\nThe following command categories are explicitly blocked for security:\n\n- ❌ File modification (rm, mv, cp, chmod, chown)\n- ❌ System administration (sudo, su, mount, fdisk)\n- ❌ Network operations (wget, curl, ssh, nc)\n- ❌ Process control (kill, killall, pkill)\n- ❌ Shell features (eval, exec, source, bash)\n- ❌ Package installation (apt, yum, pip, npm install)\n\n## 📊 MCP Tools & Resources\n\n### Tools\n- execute_safe_command - Execute whitelisted commands\n- list_available_commands - Show available commands\n- validate_command - Test command validity\n- get_server_status - Server health and statistics\n\n### Resources\n- command_history - Recent command execution history\n- security_log - Security events and audit trail\n- server_config - Current server configuration\n\n### Prompts\n- explore_project - Guided project structure exploration\n- check_git_status - Git repository status check\n- project_health_check - Overall project health assessment\n\n## ⚙️ Configuration Options\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| MAX_REQUESTS_PER_MINUTE | 30 | Rate limiting |\n| COMMAND_TIMEOUT_MS | 10000 | Command timeout |\n| MAX_OUTPUT_SIZE_BYTES | 1048576 | Max output size (1MB) |\n| ALLOWED_DIRECTORIES | current dir | Comma-separated allowed paths |\n| DEFAULT_WORKING_DIR | current dir | Default execution directory |\n| LOG_LEVEL | info | Logging level |\n| ENABLE_GIT_COMMANDS | true | Enable git operations |\n| ENABLE_NPM_COMMANDS | true | Enable npm operations |\n| ENABLE_SYSTEM_INFO | true | Enable system info commands |\n\n### CLI Options\n\nbash\n# Set log level\nnpm start -- --log-level debug\n\n# Change working directory\nnpm start -- --working-dir /path/to/workspace\n\n# Adjust timeout\nnpm start -- --timeout 15000\n\n# Disable features\nnpm start -- --disable-git --disable-npm\n\n\n## 🧪 Testing\n\nbash\n# Run all tests\nnpm test\n\n# Run security-specific tests\nnpm run test:security\n\n# Run with coverage\nnpm run test:coverage\n\n# Lint code\nnpm run lint\n\n\n## 📚 Documentation\n\n- Security Guide - Detailed security analysis\n- Claude Desktop Integration - Setup instructions\n- API Reference - MCP tools and resources\n- Troubleshooting - Common issues\n\n## 🚨 Security Considerations\n\n### Before Deployment\n\n1. Review Allowed Directories: Ensure paths are appropriate\n2. Validate Command Whitelist: Verify only necessary commands enabled\n3. Configure Rate Limits: Set appropriate limits for your use case\n4. Monitor Logs: Set up log monitoring and alerting\n5. Regular Updates: Keep dependencies and security patches current\n\n### Production Recommendations\n\n- Use dedicated user account with minimal privileges\n- Implement log rotation and monitoring\n- Set up network segmentation if needed\n- Regular security audits and penetration testing\n- Monitor for suspicious command patterns\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (git checkout -b feature/amazing-feature)\n3. Commit changes (git commit -m 'Add amazing feature')\n4. Push to branch (git push origin feature/amazing-feature)\n5. Open a Pull Request\n\n### Security Contributions\n\nSecurity improvements are especially welcome! Please:\n\n- Include security test cases\n- Document threat model changes\n- Follow responsible disclosure for vulnerabilities\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- Model Context Protocol by Anthropic\n- MCP TypeScript SDK\n- Security best practices from OWASP and NIST\n\n## 📞 Support\n\n- Issues: GitHub Issues\n- Security: See SECURITY.md for reporting vulnerabilities\n- Discussions: GitHub Discussions\n\n---\n\n**⚠️ Security Notice**: This server is designed for safe terminal access but should be deployed with appropriate security considerations. Review the security documentation before production use.\n