使用说明
🛡️ WinElevate-MCP
Break through Windows permission walls. Let your AI agent work without limits.
😤 The Problem
Ever seen your AI coding agent crash into a wall like this?
Error: EPERM: operation not permitted, open 'C:\Windows\System32\drivers\etc\hosts'
Error: EBUSY: resource busy or locked, open 'C:\ProgramData\config.dat'
When AI agents (like Claude Code) work on Windows, three things constantly break their flow:
| 💥 Pain Point | What Happens |
|---|---|
| 🔒 EPERM / UAC | Can't touch system files, protected dirs, or registry-linked configs |
| 🔐 EBUSY | Windows file locking blocks access to files held by other processes |
| 🔀 Path Mismatch | Git Bash paths (/c/Windows/...) ≠ Windows paths (C:\Windows\...) |
Result? The AI stops, asks you to do it manually, and the magic of autonomous coding is gone. 😩
✨ The Solution
WinElevate-MCP is a lightweight MCP server that hands your AI agent the master key 🔑 to Windows — admin-level file system access over stdio, with automatic path normalization.
🧰 Three Tools, Zero Friction
| Tool | What It Does |
|---|---|
📖 win_admin_read |
Read any file with admin privileges — even locked system files |
✏️ win_admin_write |
Write files anywhere — auto-creates parent directories |
🛠️ win_fix_acl |
Take ownership & reset ACL permissions via takeown + icacls |
🔄 Automatic Path Normalization
No more path headaches. All tools auto-convert Git Bash / WSL paths:
/c/Windows/System32 → C:\Windows\System32 ✅
/d/Users/test → D:\Users\test ✅
C:\Users\test → C:\Users\test ✅ (unchanged)
🚀 Quick Start
Prerequisites
- 🪟 Windows 10 / 11
- 💚 Node.js >= 18
- 👑 Administrator terminal (for full functionality)
Installation
git clone https://github.com/user/WinElevate-MCP.git
cd WinElevate-MCP
npm install
Mount in Claude Code
Open an Administrator terminal, launch Claude Code, then run:
/mcp add winelevate node "C:\path\to\WinElevate-MCP\index.js"
That's it! 🎉 The three tools are now available to your AI agent.
Standalone Mode
node index.js
The server communicates over stdio and waits for MCP JSON-RPC requests on stdin.
📖 Tool Reference
📖 win_admin_read
Read a file with administrator privileges. Overcomes EPERM/EBUSY errors.
| Parameter | Type | Required | Description |
|---|---|---|---|
filePath |
string | ✅ | Absolute path of the file to read |
encoding |
string | ❌ | File encoding (default: utf8) |
✏️ win_admin_write
Write content to a file with administrator privileges. Creates parent directories if they don't exist.
| Parameter | Type | Required | Description |
|---|---|---|---|
filePath |
string | ✅ | Absolute path of the file to write |
content |
string | ✅ | Content to write |
encoding |
string | ❌ | File encoding (default: utf8) |
🛠️ win_fix_acl
Take ownership and grant Administrators full control over a file or directory using takeown and icacls.
| Parameter | Type | Required | Description |
|---|---|---|---|
targetPath |
string | ✅ | Absolute path of the file or directory to fix |
🏗️ Architecture
┌──────────────┐ stdio ┌──────────────────┐
│ Claude Code │ ◄──────────► │ WinElevate-MCP │
│ (AI Agent) │ JSON-RPC │ (Node.js MCP) │
└──────────────┘ └────────┬─────────┘
│
┌────────▼─────────┐
│ Windows Admin │
│ • fs.readFile │
│ • fs.writeFile │
│ • takeown/icacls │
└──────────────────┘
⚠️ Security Notice
This tool provides administrator-level file access. Please use responsibly:
- 🎯 Only use when standard operations fail
- 🔍 Review AI actions in protected directories
- 🚫 Do not expose this server to untrusted networks
- 🛡️ Run in a controlled development environment
🤝 Contributing
Contributions are welcome! Feel free to:
- 🍴 Fork the repository
- 🌿 Create a feature branch (
git checkout -b feature/awesome) - 💾 Commit your changes (
git commit -m 'Add awesome feature') - 📤 Push to the branch (
git push origin feature/awesome) - 🎁 Open a Pull Request
📄 License
This project is licensed under the MIT License.
Built with ❤️ for Windows developers who refuse to let permissions slow them down.
