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!)

# 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.

{
  "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.

{
  "path": "/home/user/projects",
  "shell": "wsl"
}

3. check_path

Verify if a path exists and get detailed information.

{
  "path": "C:\\Users\\username\\Documents",
  "shell": "powershell"
}

4. open_windows_app

Launch Windows applications with advanced options.

{
  "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)

{
  "command": "rm -rf /tmp/safe-to-delete",
  "confirmed": true
}

[PACKAGE] Installation Methods

Method 1: Quick Setup (Recommended)

# No installation needed - setup automatically downloads
npx ez-mcp setup claude

Method 2: Global Installation

npm install -g ez-mcp
ez-mcp setup claude

Method 3: Manual Setup Scripts

# 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

{
  "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

// 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

// 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

// 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

// List files
{"command": "ls -la", "shell": "bash"}

// Windows directory listing  
{"command": "dir", "shell": "cmd"}

// PowerShell processes
{"command": "Get-Process", "shell": "powershell"}

Advanced Usage

// 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

{
  "mcpServers": {
    "ez-mcp": {
      "command": "npx",
      "args": ["ez-mcp"]
    }
  }
}

[DEBUG] Troubleshooting

WSL Issues

# 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 file for details.

[SUPPORT] Support

• Issues: GitHub 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!