Provides a secure interface to execute shell commands on the host system with features such as command output capture, working directory specification, command timeouts, and enhanced security controls.
Lilith Shell
⚠️ IMPORTANT SECURITY WARNING: This MCP server grants AI assistants unrestricted ability to execute terminal commands on your system. Only use in controlled environments like virtual machines (VMs) or development systems you can afford to rebuild.
About
Lilith Shell is an enhanced MCP server that empowers AI assistants to execute terminal commands on your system with improved security controls and testing. Due to the unrestricted access this provides, it's crucial to use this software responsibly and be fully aware of the security risks involved.
Note: This server is compatible with any AI assistant that supports the Model Context Protocol (MCP). The provided configuration and setup instructions are specifically tailored for Claude Desktop, which offers comprehensive support for all MCP features.
Features
Execute shell commands with security validation
Capture command output (stdout/stderr)
Set working directory
Handle command timeouts
Improved test coverage
Enhanced security controls
FastMCP integration
API
Tools
execute_command
Execute shell commands and return their output
Inputs:
command
(string): Command to executedirectory
(string, optional): Working directory
Returns:
Command exit code
Standard output
Standard error
Features:
5-minute timeout
Working directory support
Error handling
Security validation
Installation
Prerequisites
Claude Desktop with an active Claude Pro/Enterprise subscription
Download from: Claude AI
Python 3.10 or higher
Git
uv (required for package management)
Windows Installation
Install Prerequisites:
Option A - Using winget (if available on your system):
winget install python gitOption B - Manual installation (recommended):
Download and install Python from python.org
Download and install Git from git-scm.com
Install uv:
Open Command Prompt (
cmd.exe
) as administrator and run:powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"If you encounter any issues, you may need to restart your terminal or computer for the changes to take effect.
Clone and set up the project:
git clone https://github.com/charles-adedotun/Lilith-Shell.git cd Lilith-ShellThen create a virtual environment. Try these commands in order until one works:
python -m venv venvIf that doesn't work, try:
python3 -m venv venvThen activate the environment:
venv\Scripts\activateInstall dependencies:
uv pip install -e ".[dev]"
Note: If you installed Python from python.org, you'll typically use python
. If you installed via winget or from the Microsoft Store, you might need to use python3
. Try both commands if one doesn't work.
macOS Installation
Install Prerequisites:
brew install python git uvClone and set up the project:
git clone https://github.com/charles-adedotun/Lilith-Shell.git cd Lilith-Shell python3 -m venv venv source venv/bin/activateInstall dependencies:
uv pip install -e ".[dev]"
Configuration
Windows
Locate the correct configuration directory - try these paths in order:
%APPDATA%\Claude\
(typicallyC:\Users\[YourUsername]\AppData\Roaming\Claude\
)%LOCALAPPDATA%\AnthropicClaude\
(typicallyC:\Users\[YourUsername]\AppData\Local\AnthropicClaude\
)
Create or edit claude_desktop_config.json
in the correct directory:
Important Notes for Windows:
Use forward slashes (
/
) in paths, not backslashes (\
)Replace
[YourUsername]
with your actual Windows usernameFile must be named exactly
claude_desktop_config.json
If both possible config locations exist, try each until successful
macOS
Create or edit ~/Library/Application Support/Claude/claude_desktop_config.json
:
Important Notes for macOS:
Replace
[YourUsername]
with your actual usernameYou can use
$HOME
instead of/Users/[YourUsername]
if preferredFile must be named exactly
claude_desktop_config.json
The
command
path should point to the Python interpreter inside your virtual environment (venv/bin/python
), not the system Python
After Configuration
Restart Claude Desktop completely (quit/exit, not just close the window).
Click the 🔌 icon to verify the server appears in the "Installed MCP Servers" list.
If the server doesn't appear, check Claude's logs:
Windows:
%APPDATA%\Claude\Logs\mcp*.log
or%LOCALAPPDATA%\AnthropicClaude\Logs\mcp*.log
macOS:
~/Library/Logs/Claude/mcp*.log
Security Considerations
This server executes commands with your user privileges. Take these precautions:
Use only in VMs or disposable development environments.
Never use on production systems or machines with sensitive data.
Consider implementing command restrictions if needed.
Monitor system access and activity.
Keep backups of important data.
Disclaimer: The developers are not responsible for any damages or losses resulting from the use of this software. Use it at your own risk.
Troubleshooting
If you encounter issues:
Check logs:
Windows:
%APPDATA%\Claude\Logs\mcp*.log
or%LOCALAPPDATA%\AnthropicClaude\Logs\mcp*.log
macOS:
~/Library/Logs/Claude/mcp*.log
Verify installation:
Ensure
uv
is properly installed and in your PATH.Check that
mcp
package is installed:pip show mcp
.Verify Python version is 3.10 or higher.
Configuration issues:
Double-check all paths in
claude_desktop_config.json
.Verify JSON syntax is valid.
Ensure proper path separators for your OS.
Confirm config file is in the correct location.
Environment issues:
Make sure
virtualenv
is activated if using one.Verify
PYTHONPATH
is set correctly.Check file permissions.
Test server manually:
# First, make sure you're in the Lilith-Shell directory: cd /path/to/cloned/Lilith-Shell # For macOS: ./venv/bin/python src/lilith_shell/executor.py # For Windows: .\venv\Scripts\python.exe src\lilith_shell\executor.py # The executor will appear to hang with no output - this is normal. # It's waiting for connections from Claude Desktop. # Use Ctrl+C to stop it.Connection issues:
If you get "Could not connect to MCP server" errors, ensure you're using the virtual environment's Python interpreter in your config file.
For macOS: Use
/path/to/cloned/Lilith-Shell/venv/bin/python
For Windows: Use
C:/path/to/cloned/Lilith-Shell/venv/Scripts/python.exe
Testing
After setup, try these commands in Claude Desktop:
or
Acknowledgments
This project is a fork of Pandoras-Shell by Christian Hägg, with significant enhancements to security, testing, and functionality. The original project provided the foundation and inspiration for Lilith Shell.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
An enhanced MCP server that grants AI assistants the ability to execute terminal commands on a user's system with improved security controls, designed for use in controlled environments.
Related MCP Servers
- -securityFlicense-qualityAn MCP server that allows AI assistants like Claude to execute terminal commands on the user's computer and return the output, functioning like a terminal through AI.Last updated -60
- AsecurityAlicenseAqualityA server that enables AI assistants to execute terminal commands and retrieve outputs via the Model Context Protocol (MCP).Last updated -317MIT License
- AsecurityFlicenseAqualityAn MCP server that allows AI models to execute system commands on local machines or remote hosts via SSH, supporting persistent sessions and environment variables.Last updated -11524
- -securityAlicense-qualityGive hands to AI. MCP server to run shell commands securely, auditably, and on demand.Last updated -30MIT License