charles-adedotun/Lilith-Shell

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 commands
• LILITH_WORK_DIR - Restrict execution to specific directory
• LILITH_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

1. Security First - Every command validated before execution
2. Fail Safe - Unknown commands rejected by default in strict mode
3. Auditability - All commands logged with timestamp and result
4. Isolation - No access to shell history or persistent state
5. 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 deletion
• format, mkfs - Filesystem formatting
• dd - Low-level disk operations
• chmod 777 - Dangerous permission changes
• curl | sh, wget | sh - Pipe to shell execution
• sudo without 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

1. Use Strict Mode in Production - Allowlist specific commands
2. Set Conservative Timeouts - Prevent resource exhaustion
3. Monitor Audit Logs - Review command history regularly
4. Restrict Working Directory - Limit filesystem access scope
5. Review AI Requests - Understand commands before approval
6. Use Environment Isolation - Run in dedicated development environments
7. 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

1. Verify MCP server running: Check Claude Desktop logs
2. Check security mode: May be blocked in strict/lockdown mode
3. 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.