Lilith Shell
MCP server enabling AI assistants to execute terminal commands securely.
Security Warning
This tool gives AI agents shell access to your system. Only use in controlled environments. Review all security settings before deployment. Understand the risks.
Why This Exists
You want Claude to run shell commands but need security guardrails. Direct shell access is dangerous. No access is limiting. This server provides the middle ground: controlled command execution with timeout protection, error handling, and security validation.
What It Does
Provides Claude Desktop with secure shell command execution:
- Command Execution - Run terminal commands through MCP protocol
- Timeout Protection - Commands auto-terminate after configurable duration
- Security Validation - Pre-execution command analysis and filtering
- Error Handling - Structured error responses with context
- Cross-Platform - Works on macOS and Windows (PowerShell + cmd)
Tech Stack
- Python 3.10+
- FastMCP for Model Context Protocol integration
- Cross-platform subprocess management
- Security-first architecture
Key Features
Security Controls
- Command Allowlisting - Optional whitelist of permitted commands
- Dangerous Command Detection - Blocks destructive operations (rm -rf, format, etc.)
- Timeout Enforcement - Kills runaway processes
- Working Directory Control - Restricts command execution paths
- Output Sanitization - Filters sensitive data from responses
Execution Features
- Async Operations - Non-blocking command execution
- Stream Output - Real-time command output streaming
- Exit Code Handling - Proper success/failure detection
- Environment Variables - Controlled environment passing
- Shell Selection - Choose bash, zsh, PowerShell, or cmd
Quick Start
Installation - macOS
pip install lilith-shell
Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"lilith-shell": {
"command": "python",
"args": ["-m", "lilith_shell"],
"env": {
"LILITH_TIMEOUT": "30",
"LILITH_SHELL": "bash"
}
}
}
}
Installation - Windows
pip install lilith-shell
Add to Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"lilith-shell": {
"command": "python",
"args": ["-m", "lilith_shell"],
"env": {
"LILITH_TIMEOUT": "30",
"LILITH_SHELL": "powershell"
}
}
}
}
Restart Claude Desktop.
Configuration
Environment Variables
LILITH_TIMEOUT- Command timeout in seconds (default: 30)LILITH_SHELL- Shell to use (bash/zsh/powershell/cmd)LILITH_ALLOW_LIST- Comma-separated list of allowed commandsLILITH_WORK_DIR- Restrict execution to specific directoryLILITH_MAX_OUTPUT- Maximum output size in bytes (default: 1MB)
Security Modes
Permissive Mode (default) - Blocks obvious dangerous commands:
{
"env": {
"LILITH_MODE": "permissive"
}
}
Strict Mode - Only allowlisted commands execute:
{
"env": {
"LILITH_MODE": "strict",
"LILITH_ALLOW_LIST": "git,npm,pip,ls,cat,grep"
}
}
Lockdown Mode - Read-only operations only:
{
"env": {
"LILITH_MODE": "lockdown"
}
}
Architecture
lilith-shell/
├── core/
│ ├── executor.py # Command execution engine
│ ├── security.py # Security validation
│ └── timeout.py # Timeout management
├── platform/
│ ├── unix.py # macOS/Linux implementation
│ ├── windows.py # Windows implementation
│ └── base.py # Platform interface
├── utils/
│ ├── config.py # Configuration management
│ ├── logger.py # Audit logging
│ └── sanitizer.py # Output sanitization
└── server.py # MCP server entry point
Design Principles
- Security First - Every command validated before execution
- Fail Safe - Unknown commands rejected by default in strict mode
- Auditability - All commands logged with timestamp and result
- Isolation - No access to shell history or persistent state
- MCP Native - Clean integration with Model Context Protocol
Usage
Claude Desktop automatically uses the shell server when command execution is needed. Example interactions:
User: "List files in the current directory"
Claude: *executes `ls -la` via Lilith Shell*
User: "Install dependencies"
Claude: *executes `npm install` via Lilith Shell*
Blocked Commands (Permissive Mode)
These commands are blocked by default for safety:
rm -rf,rm -fr- Recursive deletionformat,mkfs- Filesystem formattingdd- Low-level disk operationschmod 777- Dangerous permission changescurl | sh,wget | sh- Pipe to shell executionsudowithout specific allowlist entry- PowerShell
Remove-Item -Recurse
Future Ideas
- Command Allowlisting UI - Web interface for managing permitted commands
- Audit Logging - Comprehensive command history with playback
- Linux Support - Full testing and optimization for Linux distros
- Sandbox Mode - Execute commands in isolated containers
- Command Templates - Pre-approved command patterns with parameters
- Rate Limiting - Prevent command spam/abuse
- Multi-User Support - Per-user security profiles
- Output Streaming UI - Real-time command output visualization
Security Best Practices
- Use Strict Mode in Production - Allowlist specific commands
- Set Conservative Timeouts - Prevent resource exhaustion
- Monitor Audit Logs - Review command history regularly
- Restrict Working Directory - Limit filesystem access scope
- Review AI Requests - Understand commands before approval
- Use Environment Isolation - Run in dedicated development environments
- Keep Updated - Security patches applied promptly
Troubleshooting
Commands Timing Out
Increase timeout: "LILITH_TIMEOUT": "60"
Permission Denied Errors
Check working directory permissions and command allowlist.
Commands Not Executing
- Verify MCP server running: Check Claude Desktop logs
- Check security mode: May be blocked in strict/lockdown mode
- Review audit logs:
~/.config/lilith-shell/logs/audit.log
Development
# Clone repository
git clone https://github.com/charles-adedotun/Lilith-Shell.git
cd lilith-shell
# Install dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Security audit
bandit -r src/
# Type checking
mypy src/
Contributing
Security issues get priority. Open a private security advisory for vulnerabilities. For features, open an issue first to discuss approach. Keep security validation strict.
License
MIT
Acknowledgments
Built for developers who need AI shell access without the chaos. Use responsibly.