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

$3

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



$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

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

EZ-MCP: Easy Model Context Protocol Server

>>> Quick Start

$3

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



$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

[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