A simple Model Context Protocol (MCP) server for executing command-line tools across different shell environments (WSL, PowerShell, CMD, Bash). Easy setup for Claude Desktop, GitHub Copilot, LM Studio, and Cursor.
npm install ez-mcpbash
Setup for Claude Desktop
npx ez-mcp setup claude
Setup for GitHub Copilot (VS Code)
npx ez-mcp setup copilot
Setup for LM Studio
npx ez-mcp setup lmstudio
Setup for Cursor IDE
npx ez-mcp setup cursor
`
That's it! The setup automatically:
- [+] Downloads and configures the MCP server
- [+] Updates your AI tool's configuration
- [+] Preserves existing MCP servers
- [+] Works across Windows, Mac, and Linux
[STRUCTURE] Project Structure
`
ez-mcp/
├── src/ # TypeScript source code
├── build/ # Compiled JavaScript files
├── scripts/ # Setup scripts for manual installation
│ ├── setup.bat # Windows batch script
│ ├── setup.ps1 # PowerShell script
│ └── setup.sh # Unix/Linux shell script
├── test/ # Test files
└── package.json # NPM configuration
`
The setup scripts in the scripts/ folder are provided for manual installation scenarios where npx might not be available.
[TOOLS] Features
$3
Execute commands in any shell environment:
- Windows: PowerShell, CMD
- Linux/WSL: Bash, Zsh, Sh
- WSL Integration: Target specific distributions
$3
- 25+ Dangerous Command Patterns detected
- Absolute blocking of destructive operations without confirmation
- Smart warnings with clear consequences
- Audit logging for security compliance
$3
- Launch any Windows application safely
- Command-line arguments support
- Working directory configuration
- Multiple launch methods
$3
- One-command setup for popular AI tools
- Cross-platform compatibility
- Zero configuration for basic usage
- Extensible and maintainable
[TOOLS] Available Tools
$3
Execute any command in your preferred shell environment.
`json
{
"command": "ls -la",
"shell": "bash",
"workingDirectory": "/home/user/projects"
}
`
Parameters:
- command (required): The command to execute
- shell (optional): wsl, powershell, cmd, bash, zsh, sh (default: powershell)
- workingDirectory (optional): Working directory for command execution
- timeout (optional): Command timeout in milliseconds (default: 30000)
- wslDistribution (optional): Specific WSL distribution name
- confirmed (optional): Set to true for dangerous commands (see Security section)
$3
List contents of any directory across different shell environments.
`json
{
"path": "/home/user/projects",
"shell": "wsl"
}
`
$3
Verify if a path exists and get detailed information.
`json
{
"path": "C:\\Users\\username\\Documents",
"shell": "powershell"
}
`
$3
Launch Windows applications with advanced options.
`json
{
"app": "notepad",
"arguments": "C:\\temp\\file.txt",
"workingDirectory": "C:\\temp"
}
`
[SECURE] Security Features
$3
EZ-MCP automatically detects and blocks 25+ dangerous command patterns to prevent accidental system damage:
#### [CRITICAL] CRITICAL COMMANDS (Require Confirmation)
- Disk Operations: format, fdisk, diskpart
- Recursive Deletion: rm -rf /, del C:\*, rmdir /s
- System Control: shutdown, restart, reboot
- Registry: reg delete, regedit
- Process Control: taskkill /f, stop-process -force
- Container Ops: docker system prune -f, kubectl delete
- Git Destructive: git reset --hard, git clean -fd
- Database: drop database, truncate table
#### [WARN] Security Warning Example
`
[DANGER] DANGEROUS COMMAND BLOCKED [DANGER]
[BLOCKED] EXECUTION REFUSED FOR SAFETY
[CRITICAL] DISK FORMATTING/PARTITIONING - PERMANENT DATA LOSS
[WARN] POTENTIAL CONSEQUENCES:
• Permanent data loss
• System corruption or instability
• Complete system failure
[SECURITY] SECURITY REQUIREMENT:
This command will ONLY execute if you explicitly set "confirmed": true
`
#### [+] Safe Override (Use with EXTREME caution)
`json
{
"command": "rm -rf /tmp/safe-to-delete",
"confirmed": true
}
`
[PACKAGE] Installation Methods
$3
`bash
No installation needed - setup automatically downloads
npx ez-mcp setup claude
`
$3
`bash
npm install -g ez-mcp
ez-mcp setup claude
`
$3
`bash
Clone the repository
git clone https://github.com/thechandanbhagat/ez-mcp.git
cd ez-mcp
Run platform-specific setup script
Windows (Command Prompt)
scripts\setup.bat
Windows (PowerShell)
scripts\setup.ps1
Linux/Mac/WSL
chmod +x scripts/setup.sh
scripts/setup.sh
`
$3
`json
{
"mcpServers": {
"ez-mcp": {
"command": "npx",
"args": ["ez-mcp"]
}
}
}
`
[TARGET] Use Cases
$3
- Execute system commands through Claude, Copilot, etc.
- File system operations and navigation
- Development workflow automation
- System monitoring and diagnostics
$3
`json
// Build and test projects
{"command": "npm run build && npm test", "shell": "bash"}
// Git operations
{"command": "git status && git log --oneline -5", "shell": "bash"}
// Cross-platform development
{"command": "ls -la", "shell": "wsl", "wslDistribution": "Ubuntu"}
`
$3
`json
// Check system resources
{"command": "Get-Process | Sort-Object CPU -Desc | Select-Object -First 10", "shell": "powershell"}
// Monitor disk space
{"command": "df -h", "shell": "bash"}
// Network diagnostics
{"command": "ping -c 4 google.com", "shell": "bash"}
`
$3
`json
// Launch applications
{"app": "code", "arguments": ".", "workingDirectory": "C:\\Projects"}
// Open system tools
{"app": "taskmgr", "method": "start"}
// Start with specific settings
{"app": "notepad++", "arguments": "file.txt", "waitForExit": true}
`
[QUICK] Examples
$3
`json
// List files
{"command": "ls -la", "shell": "bash"}
// Windows directory listing
{"command": "dir", "shell": "cmd"}
// PowerShell processes
{"command": "Get-Process", "shell": "powershell"}
`
$3
`json
// WSL with specific distribution
{
"command": "uname -a && lsb_release -a",
"shell": "wsl",
"wslDistribution": "Ubuntu-20.04"
}
// Working directory execution
{
"command": "npm install && npm start",
"shell": "bash",
"workingDirectory": "/home/user/project",
"timeout": 60000
}
// Windows app with arguments
{
"app": "C:\\Program Files\\VSCode\\Code.exe",
"arguments": "--new-window .",
"workingDirectory": "C:\\Projects\\MyApp"
}
`
[TOOLS] Configuration
$3
| Tool | Status | Setup Command |
|------|--------|---------------|
| Claude Desktop | [+] Fully Supported | npx ez-mcp setup claude |
| GitHub Copilot | [+] VS Code Integration | npx ez-mcp setup copilot |
| LM Studio | [+] Local Models | npx ez-mcp setup lmstudio |
| Cursor IDE | [+] AI Code Editor | npx ez-mcp setup cursor |
| Other MCP Clients | [+] Manual Config | See manual setup below |
$3
`json
{
"mcpServers": {
"ez-mcp": {
"command": "npx",
"args": ["ez-mcp"]
}
}
}
`
[DEBUG] Troubleshooting
$3
`bash
Check WSL status
wsl --list --verbose
Install WSL if missing
wsl --install
Update WSL distribution
wsl --update
`
$3
- Windows: Run terminal as Administrator for system operations
- Linux/Mac: Use sudo for privileged commands (with confirmed: true)
- WSL: Ensure WSL has proper permissions
$3
- Increase timeout parameter for long operations
- Use & for background processes in Unix shells
- Consider Start-Job for PowerShell background tasks
$3
| Issue | Solution |
|-------|----------|
| "Command not found" | Check PATH environment variable |
| "Access denied" | Run with appropriate permissions |
| "Shell not supported" | Use supported shell names |
| "WSL not available" | Install and configure WSL |
[STATS] Performance
- Lightweight: ~10KB package size
- Fast: Direct shell execution, no overhead
- Reliable: Comprehensive error handling
- Scalable: Handles concurrent command execution
[CONTRIB] Contributing
1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request
$3
- src/ - TypeScript source code
- build/ - Compiled JavaScript (auto-generated)
- scripts/ - Platform-specific setup scripts
- test/` - Test files for validation