Windows Native MCP Server 🪟🔧

Operate Windows like a local AI agent — processes, services, registry, GUI, file system, and more — all through MCP protocol.

---

What is this?

A lightweight MCP (Model Context Protocol) server that runs natively on Windows, exposing system operations as tools for any MCP-compatible AI agent — Hermes Agent, Claude Code, Cursor, or any custom MCP client.

Instead of asking "what processes are running?" and then manually checking Task Manager, your AI agent can directly call windows_process_list and get real-time results.

Features ✨

• 26 built-in tools covering process, service, registry, GUI, network, file, and system operations
• Runs silently in background — ~26 MB memory, negligible CPU
• Auto-start on login — set it and forget it
• Standard MCP protocol — works with any MCP client, not just Hermes
• 100% Windows native — uses pywin32, pyautogui, psutil for real system access

Quick Start 🚀

1. Clone & Install Dependencies

git clone https://github.com/YOUR_USERNAME/hermes-mcp-windows.git
cd hermes-mcp-windows
pip install -r server/requirements.txt

2. Start the Server

python server/windows_mcp_server.py

============================================================
  Windows Native MCP Server
  Port: 18765
  Streamable HTTP: http://localhost:18765/mcp
  Python: C:\Users\...\python.exe
  pywin32:   [OK]
  psutil:    [OK]
  pyautogui: [OK]
  Pillow:    [OK]
============================================================

3. Configure Your AI Agent

Hermes Agent — add to ~/.hermes/config.yaml:

mcp_servers:
  windows:
    url: http://localhost:18765/mcp
    timeout: 60

Then run: hermes mcp test windows → start a fresh session → all windows_* tools are available.

Any MCP client — connect to http://localhost:18765/mcp using the Streamable HTTP transport.

Auto-start on Login 🔄

Double-click setup/install_autostart.vbs — the server will start silently on every Windows login.

Remove it with setup/remove_autostart.vbs.

Tools Reference 📋

Process Management

Tool	Description
windows_process_list	List running processes (filter by name, shows PID, memory, CPU)
windows_process_kill	Kill a process by PID or name

Service Management

Tool	Description
windows_service_list	List services with status (filter by name/state)
windows_service_control	Start, stop, or restart a service

Registry

Tool	Description
windows_registry_read	Read registry values or list subkeys
windows_registry_write	Write registry values (use with caution)

System Info

Tool	Description
windows_system_info	OS version, RAM, CPU, boot time, hostname
windows_disk_info	Drive usage (total/used/free per volume)
windows_hotfix_list	Installed Windows updates
windows_startup_programs	Programs that auto-start on login

Environment Variables

Tool	Description
windows_env_get	Get environment variable(s)
windows_env_set	Set environment variable (user/machine scope)

GUI Automation (pyautogui)

Tool	Description
windows_screenshot	Take screenshot (returns base64 PNG)
windows_mouse_move	Move mouse to coordinates
windows_mouse_click	Click at coordinates (left/right/middle)
windows_type_text	Type text via keyboard
windows_key_press	Press key combination (e.g. ctrl+c, alt+tab)

Window Management

Tool	Description
windows_window_list	List all visible windows (handle, title, process, position)
windows_window_focus	Focus a window by title (partial match)

Network

Tool	Description
windows_network_info	Network adapter information (ipconfig)
windows_network_stats	Active connections (LISTEN/ESTABLISHED)

File Operations

Tool	Description
windows_file_info	Detailed file/directory info
windows_file_search	Search files by pattern (limited depth)

Execute

Tool	Description
windows_run_powershell	Run arbitrary PowerShell command
windows_run_cmd	Run arbitrary cmd.exe command

Notification

Tool	Description
windows_notification	Show Windows toast notification

Architecture 🏗️

┌──────────────────┐    MCP Streamable HTTP     ┌─────────────────────┐
│  AI Agent        │ ◄──────────────────────────►│  MCP Server         │
│  (Hermes, etc.)  │    localhost:18765/mcp      │  (Python)           │
│                  │                             │                     │
│                  │                             │  ├─ pywin32 (Win32) │
│                  │                             │  ├─ psutil (system) │
│                  │                             │  ├─ pyautogui (GUI) │
│                  │                             │  └─ subprocess (PS) │
└──────────────────┘                             └─────────────────────┘

Memory & Performance 📊

Metric	Value
RAM usage	~26 MB
CPU usage	Idle (zero when not in use)
Startup time	< 1 second

Requirements

• OS: Windows 10 or Windows 11
• Python: 3.12+
• Dependencies: mcp, pywin32, psutil, pyautogui, Pillow

Development

# Install dev dependencies
pip install mcp pywin32 psutil pyautogui pillow

# Run the server
python server/windows_mcp_server.py --port 18765

# Test tools via curl
curl -X POST http://localhost:18765/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

License

MIT — see LICENSE.