Content
# EZ-MCP: Easy Model Context Protocol Server
A simple yet powerful Model Context Protocol (MCP) server for executing command-line tools across different shell environments. Works seamlessly with Claude Desktop, GitHub Copilot, LM Studio, Cursor, and other AI tools.
## >>> Quick Start
### Installation & Setup (One Command!)
```bash
# 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
### [SYSTEM] **Multi-Shell Support**
Execute commands in any shell environment:
- **Windows**: PowerShell, CMD
- **Linux/WSL**: Bash, Zsh, Sh
- **WSL Integration**: Target specific distributions
### [SECURITY] **Military-Grade Security**
- **25+ Dangerous Command Patterns** detected
- **Absolute blocking** of destructive operations without confirmation
- **Smart warnings** with clear consequences
- **Audit logging** for security compliance
### [TARGET] **Windows Application Management**
- Launch any Windows application safely
- Command-line arguments support
- Working directory configuration
- Multiple launch methods
### [QUICK] **Developer-Friendly**
- **One-command setup** for popular AI tools
- **Cross-platform** compatibility
- **Zero configuration** for basic usage
- **Extensible** and maintainable
## [TOOLS] Available Tools
### 1. `execute_command`
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)
### 2. `list_directory`
List contents of any directory across different shell environments.
```json
{
"path": "/home/user/projects",
"shell": "wsl"
}
```
### 3. `check_path`
Verify if a path exists and get detailed information.
```json
{
"path": "C:\\Users\\username\\Documents",
"shell": "powershell"
}
```
### 4. `open_windows_app`
Launch Windows applications with advanced options.
```json
{
"app": "notepad",
"arguments": "C:\\temp\\file.txt",
"workingDirectory": "C:\\temp"
}
```
## [SECURE] Security Features
### [DANGER] **Dangerous Command Protection**
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
### Method 1: Quick Setup (Recommended)
```bash
# No installation needed - setup automatically downloads
npx ez-mcp setup claude
```
### Method 2: Global Installation
```bash
npm install -g ez-mcp
ez-mcp setup claude
```
### Method 3: Manual Setup Scripts
```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
```
### Method 4: Manual MCP Configuration
```json
{
"mcpServers": {
"ez-mcp": {
"command": "npx",
"args": ["ez-mcp"]
}
}
}
```
## [TARGET] Use Cases
### [AI] **AI Assistant Integration**
- Execute system commands through Claude, Copilot, etc.
- File system operations and navigation
- Development workflow automation
- System monitoring and diagnostics
### [DEV] **Development Workflows**
```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"}
```
### [TOOLS] **System Administration**
```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"}
```
### [WINDOWS] **Windows App Management**
```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
### Basic Commands
```json
// List files
{"command": "ls -la", "shell": "bash"}
// Windows directory listing
{"command": "dir", "shell": "cmd"}
// PowerShell processes
{"command": "Get-Process", "shell": "powershell"}
```
### Advanced Usage
```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
### Supported AI Tools
| 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 |
### Manual Configuration
```json
{
"mcpServers": {
"ez-mcp": {
"command": "npx",
"args": ["ez-mcp"]
}
}
}
```
## [DEBUG] Troubleshooting
### WSL Issues
```bash
# Check WSL status
wsl --list --verbose
# Install WSL if missing
wsl --install
# Update WSL distribution
wsl --update
```
### Permission Errors
- **Windows**: Run terminal as Administrator for system operations
- **Linux/Mac**: Use `sudo` for privileged commands (with `confirmed: true`)
- **WSL**: Ensure WSL has proper permissions
### Command Timeouts
- Increase `timeout` parameter for long operations
- Use `&` for background processes in Unix shells
- Consider `Start-Job` for PowerShell background tasks
### Common Issues
| 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
### Development Setup
- `src/` - TypeScript source code
- `build/` - Compiled JavaScript (auto-generated)
- `scripts/` - Platform-specific setup scripts
- `test/` - Test files for validation
## [LICENSE] License
MIT License - see [LICENSE](LICENSE) file for details.
## [SUPPORT] Support
- **Issues**: [GitHub Issues](https://github.com/thechandanbhagat/ez-mcp/issues)
- **Documentation**: This README + inline help
- **Security**: Report security issues via GitHub Security tab
## >>> What's Next?
- **v1.1**: Enhanced logging and audit trails
- **v1.2**: Plugin system for custom commands
- **v1.3**: Web UI for command management
- **v2.0**: Distributed execution and clustering
---
**[STAR] Star this repo if EZ-MCP helps your AI workflow!**
