Windows Management MCP Server
by AstraxOf
README.md
<!-- mcp-name: io.github.ahmedlaminou/windows-mcp-server -->
<div align="center">
# 🪟 Windows Management MCP Server
**Let your AI assistant inspect, diagnose and manage your Windows PC through the Model Context Protocol: 97 tools, local, over stdio.**
[](README.md)
[](README.es.md)
[](https://github.com/AhmedLaminou/windows-mcp-server/actions)
[](https://t.me/AstraxMCP)
[](https://youtube.com/@AstraxOf)
[](https://astrabots.pro)
[](https://github.com/AstraxOf)
</div>
---
> **Windows Management MCP Server** is a Python server for the [Model Context Protocol](https://modelcontextprotocol.io) that exposes **97 tools** for local Windows diagnostics, task management, cleanup, hardware inspection, security checks and administration. It works with Claude Desktop, Cursor, VS Code and any other MCP-compatible client.
> [!IMPORTANT]
> This server runs with the privileges of the account that starts it. Some tools can delete files, edit the Registry, manage services, install updates or run PowerShell. **Start with the read-only and dry-run tools** and only allow destructive actions after reviewing the target paths and commands.
> [!NOTE]
> **Credits.** This project was created by **[Ahmed Laminou Amadou (@AhmedLaminou)](https://github.com/AhmedLaminou)**, the original author and maintainer: the architecture and the original 96 tools are his work. This version updates it to keep it running with the new MCP Python SDK and adds one small tool (see [What's new](#-whats-new-in-this-version)).
**Jump to:** [What's new](#-whats-new-in-this-version) · [Install](#-installation) · [Connect a client](#-connect-your-mcp-client) · [What it can do](#-what-it-can-do) · [Safety](#-safety-model) · [Troubleshooting](#-something-not-working) · [Credits](#-credits--license)
## 🆕 What's new in this version
The official MCP Python SDK **v2.0.0 (July 28, 2026)** renamed `FastMCP` to **`MCPServer`** and moved the module from `mcp.server.fastmcp` to `mcp.server.mcpserver`, with no deprecation shim. Since `pip install mcp` now installs 2.x, a fresh install of the old code crashed on start-up with `ModuleNotFoundError`.
| Change | Detail |
|---|---|
| ✅ **Works with `mcp` 2.x** | Uses `MCPServer`. |
| ✅ **Still works with `mcp` 1.x** | Falls back to `FastMCP` automatically. |
| 🧹 **Unused dependency removed** | The standalone `fastmcp` package was listed but never imported. |
| 🔒 **Safer version range** | `mcp>=1.12,<3`, so the next major release can't break installs silently. |
| 🎁 **New tool** | `get_server_status` reports server and SDK versions, loaded tools and whether the server is running as Administrator. |
| 🧪 **Tests + CI** | Import, tool-count and `list_tools()` checks on Python 3.10/3.13 against both SDK generations. |
| 📝 **Docs** | New English and Spanish READMEs. |
> 💡 **Not the same thing:** the standalone [`fastmcp`](https://gofastmcp.com) framework was **not** renamed. Only the class built into the official `mcp` SDK was.
Full details in the [CHANGELOG](CHANGELOG.md).
## 🧩 How it works
```mermaid
flowchart LR
A["🤖 AI client<br/>Claude Desktop · Cursor · VS Code"] <-->|"MCP over stdio"| B["🪟 windows-mcp-server<br/>(Python)"]
B <--> C["⚙️ PowerShell · psutil · Windows APIs"]
```
1. Your MCP client launches `windows-mcp-server` as a local process.
2. The assistant sees the 97 tools and decides which one to call.
3. The server runs it on your PC and returns the result. Nothing is sent to third-party servers.
## ✅ What you need
| Requirement | Notes |
|---|---|
| **Windows 10 / 11 / Server** with PowerShell | Check with `$PSVersionTable`. |
| **Python 3.10 or newer** | `python --version`. Get it from [python.org](https://www.python.org/downloads/) and tick **“Add Python to PATH”**. |
| **An MCP client** | Claude Desktop, Cursor, VS Code, etc. |
Some tools need **Administrator** privileges or optional Windows features. NVIDIA telemetry needs `nvidia-smi` on your `PATH`.
## 🚀 Installation
**From PyPI:**
```powershell
pip install windows-management-mcp-server
```
**From source (recommended if you want to modify it):**
```powershell
git clone https://github.com/AhmedLaminou/windows-mcp-server.git
cd windows-mcp-server
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e .
```
Both options register the `windows-mcp-server` command in the active environment.
## 🔌 Connect your MCP client
Add this to your client's MCP configuration (for Claude Desktop: `claude_desktop_config.json`):
```json
{
"mcpServers": {
"windows-management": {
"command": "windows-mcp-server",
"args": []
}
}
}
```
If the command isn't on your `PATH`, point to the virtual environment:
```json
{
"mcpServers": {
"windows-management": {
"command": "C:\\path\\to\\windows-mcp-server\\venv\\Scripts\\python.exe",
"args": ["-m", "windows_mcp_server.server"]
}
}
}
```
You can also run it by hand (`windows-mcp-server` or `python -m windows_mcp_server.server`), but it speaks stdio, so it's meant to be launched by a client.
**VS Code:** the [`vscode-extension/`](vscode-extension) folder contains a small extension that launches the server (repo-local venv first, then the global command). Run `npm install && npm run compile`, open the folder in VS Code and press `F5`.
## 🛠️ What it can do
| Area | Examples |
|---|---|
| 📊 **Task manager** | CPU, GPU, memory, disk, top processes, process trees, suspend / resume / kill. |
| 🧹 **Storage & cleanup** | Largest folders and files, duplicates, old files, media, Recycle Bin deletion, temp cleanup. |
| 🖥️ **Hardware & drivers** | GPU info, `nvidia-smi`, displays, installed drivers, problem devices, driver update candidates. |
| 🛡️ **Security** | Defender status/scans, firewall rules, BitLocker, Secure Boot, UAC, Windows Update. |
| ⚙️ **Administration** | Services, startup apps, scheduled tasks, event logs, crash diagnostics, restore points. |
| 🌐 **Network** | Interfaces, sockets, listening ports, firewall correlation, ping latency. |
| 👩💻 **Developer env** | Python/Node discovery, environment variables, common dev ports. |
| 🪟 **Shell helpers** | Explorer open/select, screenshots, clipboard, visible windows. |
| 🔌 **Peripherals & virtualization** | Printers, audio, Bluetooth, WSL, Hyper-V, optional Windows features. |
The complete list is in [docs/TOOLS.md](docs/TOOLS.md).
🎬 Original demo: <https://youtu.be/1GNk_GYYkww>
## 🔐 Safety model
| Level | Examples | Advice |
|---|---|---|
| 🟢 **Read-only** | `disk_cleanup_report`, `get_security_status`, `get_windows_update_status`, `list_scheduled_tasks`, `get_process_details` | Use these first. |
| 🟡 **Safer mutation** | `safe_delete_to_recycle_bin`, `safe_delete_many_to_recycle_bin`, `safe_delete_by_pattern` (`dry_run=true`) | Reversible or previewable. |
| 🔴 **Sharp tools** | `execute_powershell`, Registry writes/deletes, permanent deletion, service changes, update installation, process termination, restore point creation | Review every call. Don't run as Administrator unless needed. |
Treat the MCP client as part of the trusted computing base. See [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md) before exposing this server to an assistant you don't fully trust.
## 🩺 Something not working?
| Symptom | Fix |
|---|---|
| `ModuleNotFoundError: No module named 'mcp.server.fastmcp'` | You're on an **old copy** of this project with `mcp` 2.x. Update to this version, or pin `pip install "mcp<2"`. |
| `windows-mcp-server` is not recognized | Activate the virtual environment, or use the `python.exe -m windows_mcp_server.server` form shown above. |
| `python` is not recognized | Reinstall Python ticking **Add Python to PATH**, or try `py`. |
| A tool says access denied | It needs an elevated terminal / Administrator. Only elevate if you trust the client. |
| `nvidia-smi` tools return nothing | Install the NVIDIA driver tools and make sure `nvidia-smi` is on `PATH`. |
| The client doesn't show the tools | Restart the client completely and check its MCP logs. |
## 🧑💻 Development
```powershell
pip install -e . pytest
python -m pytest -q tests # imports + 97 tools registered
python -m compileall windows_mcp_server # compile check
```
The tests also run on Linux/macOS (no tool is executed). See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) to add a tool and [CONTRIBUTING.md](CONTRIBUTING.md) for the pull-request checklist.
```text
windows_mcp_server/ Python MCP server package
windows_mcp_server/tools/ Tool modules grouped by Windows domain
tests/ Registration and import tests
vscode-extension/ Optional VS Code extension wrapper
docs/ Tool catalog, security model, publishing guide
server.json MCP Registry metadata
```
## 🤝 Contributing
Issues and pull requests are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md), and report security problems privately following [SECURITY.md](SECURITY.md) (never in a public issue).
[](https://t.me/AstraxMCP)
[](https://youtube.com/@AstraxOf)
[](https://t.me/RufusOficial)
[](mailto:avpn497@gmail.com)
## 🙏 Credits & License
- **Original author and maintainer:** [Ahmed Laminou Amadou](https://github.com/AhmedLaminou) · [AhmedLaminou/windows-mcp-server](https://github.com/AhmedLaminou/windows-mcp-server)
- **Compatibility update for MCP SDK 2.x and `get_server_status`:** Rufus · [@AstraxOf](https://github.com/AstraxOf) · [astrabots.pro](https://astrabots.pro)
If this project is useful to you, leave a ⭐ on the [original repository](https://github.com/AhmedLaminou/windows-mcp-server) and join the [Telegram channel](https://t.me/AstraxMCP).
<div align="center">
Made with 💙 by Rufus · [@AstraxOf](https://github.com/AstraxOf) · [astrabots.pro](https://astrabots.pro)
**[MIT License](LICENSE)** · Copyright © 2026 Ahmed Laminou Amadou
</div>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues