# Windows MCP Server

This project provides a Windows MCP (Model Context Protocol) server exposing useful system information and control tools for Windows environments on your AI applications.

## What’s new

- More robust drive and uptime implementations (no brittle PowerShell parsing).
- Structured results for top processes (list of objects with pid, name, cpu_percent, memoryMB).
- Structured results for memory and network information.
- Safer PowerShell usage with JSON parsing for GPU info.

## Features

- System info (OS, release, version, architecture, hostname)
- Uptime and last boot time
- Drives listing and per-drive space usage
- Memory, CPU, GPU, and Network information
- Top processes by memory and CPU (accurate sampling)

## Available Tools

| Tool Name                       | Description                                                 | Parameters            | Returns                                                               |
| ------------------------------- | ----------------------------------------------------------- | --------------------- | --------------------------------------------------------------------- |
| Windows-system-info             | Get OS, release, version, architecture, and hostname        | None                  | object: name, system, release, version, architecture, hostname        |
| Windows-last-boot-time          | Get the last boot time of the system                        | None                  | string (timestamp)                                                    |
| Windows-uptime                  | Get system uptime since last boot                           | None                  | string: "Uptime: <seconds> seconds"                                   |
| Windows-drives                  | Get list of all available drives                            | None                  | string[] (e.g., ["C", "D"])                                           |
| Windows-drive-status            | Get used and free space for a specific drive                | drive: string         | DriveInfo { name, used_spaceGB: number, free_spaceGB: number }        |
| Windows-drives-status-simple    | Get status using comma-separated drive letters              | drives_string: string | DriveInfo[]                                                           |
| Windows-memory-info             | Get RAM usage information                                   | None                  | object: total_memory, available_memory, used_memory (strings with GB) |
| Windows-network-info            | Get network IPv4 addresses per interface                    | None                  | object: interface -> IPv4 (or { error })                              |
| Windows-cpu-info                | Get CPU model, logical count and frequency                  | None                  | string                                                                |
| Windows-gpu-info                | Get GPU name(s) and driver versions                         | None                  | string (one line per GPU)                                             |
| Windows-top-processes-by-memory | Get the top X processes by memory usage                     | amount: int = 5       | ProcessInfo[] { pid, name, memoryMB, cpu_percent? }                   |
| Windows-top-processes-by-cpu    | Get the top X processes by CPU usage (sampled for accuracy) | amount: int = 5       | ProcessInfo[] { pid, name, cpu_percent, memoryMB }                    |

Note: Previously documented tools `Windows-name-version`, `Windows-drives-status`, and `Windows-all-drives-status` are not currently implemented to avoid duplication. If needed, they can be added easily.

## Requirements

- Python 3.13+
- uv (for fast startup and dependency management)

```powershell
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

## Installation

1. Clone this repository:

```powershell
git clone https://github.com/carlosedp/windows-mcp-server.git
cd windows-mcp-server
```

## Running the development Server

```powershell
uv run mcp dev main.py
```

`uv` handles the installation of dependencies and runs the server with the MCP protocol enabled.

Then in the MCP Inspector browser window:

- Click "Connect" to connect the MCP client.
- Go to the "Tools" tab to see available tools.
- Click "List Tools" to see the available tools.
- Select a tool and click "Run tool" to execute it.

## Examples

### Windows-system-info

```json
{
  "name": "MY-PC",
  "system": "Windows",
  "release": "10",
  "version": "10.0.19045",
  "architecture": "64bit",
  "hostname": "MY-PC"
}
```

### Windows-drive-status (input: "C")

```json
{
  "name": "C",
  "used_spaceGB": 120.53,
  "free_spaceGB": 380.12
}
```

### Windows-memory-info

```json
{
  "total_memory": "32.00 GB",
  "available_memory": "18.25 GB",
  "used_memory": "13.75 GB"
}
```

### Windows-network-info

```json
{
  "Ethernet": "192.168.1.50",
  "Wi-Fi": "10.0.0.15"
}
```

### Windows-top-processes-by-cpu (amount: 3)

```json
[
  { "pid": 1234, "name": "chrome.exe", "cpu_percent": 24.7, "memoryMB": 512.3 },
  { "pid": 4321, "name": "code.exe",   "cpu_percent": 12.1, "memoryMB": 650.8 },
  { "pid": 9876, "name": "System",     "cpu_percent": 8.4,  "memoryMB": 45.0 }
]
```

## MCP Client Configuration Example

LM Studio using Llama 3.2 3B getting system information using the MCP server:

![alt text](img/image.png)

Some more examples of tools you can run:

![alt text](img/image2.png)

To connect your MCP client to this server (like Claude Desktop, VSCode, LM Studio, etc), add the following to your client configuration:

```json
{
  "mcpServers": {
    "windows-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\Carlos Eduardo\\repos\\windows-mcp-server",
        "run",
        "mcp",
        "run",
        "main.py"
      ]
    }
  }
}
```

Adjust the paths above to where the project file is located.

## Packaging and Distribution

To publish as a Python package:

1. Edit `pyproject.toml` with your metadata.
2. Build and upload to PyPI:

```powershell
python -m build
python -m twine upload dist/*
```

## License

MIT