😤 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:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/awesome)
3. 💾 Commit your changes (git commit -m 'Add awesome feature')
4. 📤 Push to the branch (git push origin feature/awesome)
5. 🎁 Open a Pull Request

📄 License

This project is licensed under the MIT License.