ez-mcp

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

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit changes (git commit -m 'Add amazing feature')
• Push to branch (git push origin feature/amazing-feature)
• 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!