mcp-windows 0.0.1__py3-none-any.whl

mcp_windows/__init__.py

@@ -0,0 +1,4 @@
+from mcp_windows.main import mcp
+
+def main() -> None:
+    mcp.run("stdio")

mcp_windows/appid.py

@@ -0,0 +1,34 @@
+"""this script registers a start menu shortcut for the MCP Windows app with a custom AppUserModelID.
+This is necessary for the app to be able to send windows toast notifications due to some legacy UWP API
+limitations.
+
+If you press the windows key and type "mcp" in the start menu, you should see the MCP Windows app icon."""
+
+import os
+import sys
+from win32com.client import Dispatch
+import pythoncom
+
+APP_ID = "mcp-windows"
+SHORTCUT_PATH = os.path.join(
+    os.environ["APPDATA"],
+    r"Microsoft\Windows\Start Menu\Programs\MCP Windows.lnk"
+)
+
+STGM_READWRITE = 0x00000002
+
+def register_app_id():
+    shell = Dispatch("WScript.Shell")
+    shortcut = shell.CreateShortcut(SHORTCUT_PATH)
+    shortcut.TargetPath = sys.executable
+    shortcut.WorkingDirectory = os.getcwd()
+    shortcut.IconLocation = sys.executable
+    shortcut.Save()
+
+    # Add AppUserModelID
+    from win32com.propsys import propsys, pscon
+    property_store = propsys.SHGetPropertyStoreFromParsingName(SHORTCUT_PATH, None, STGM_READWRITE)
+    property_store.SetValue(pscon.PKEY_AppUserModel_ID, propsys.PROPVARIANTType(APP_ID, pythoncom.VT_LPWSTR))
+    property_store.Commit()
+
+register_app_id()

mcp_windows/main.py

@@ -0,0 +1,18 @@
+from fastmcp import FastMCP
+from os import environ
+
+from mcp_windows.media import mcp as media_mcp
+from mcp_windows.notifications import mcp as notifications_mcp
+from mcp_windows.window_management import mcp as window_management_mcp
+from mcp_windows.monitors import mcp as monitors_mcp
+
+sep = environ.get("FASTMCP_TOOL_SEPARATOR", "_")
+
+mcp: FastMCP = FastMCP(
+    name="windows",
+)
+
+mcp.mount("media", media_mcp, tool_separator=sep)
+mcp.mount("notifications", notifications_mcp, tool_separator=sep)
+mcp.mount("window_management", window_management_mcp, tool_separator=sep)
+mcp.mount("monitors", monitors_mcp, tool_separator=sep)

mcp_windows/media.py

@@ -0,0 +1,70 @@
+import json
+from fastmcp import FastMCP
+from winrt.windows.media.control import GlobalSystemMediaTransportControlsSessionManager as MediaManager, GlobalSystemMediaTransportControlsSessionMediaProperties as MediaProperties
+from winrt.windows.foundation import IAsyncOperation
+
+mcp: FastMCP = FastMCP(
+    name="Media",
+)
+
+@mcp.tool("get_media_sessions")
+async def get_media_sessions() -> str:
+    """List all media playback sessions using windows media control API."""
+
+    manager_op: IAsyncOperation = MediaManager.request_async()
+    manager = await manager_op
+    sessions = manager.get_sessions()
+
+    output = {}
+    for session in sessions:
+        props_op = session.try_get_media_properties_async()
+        props: MediaProperties = await props_op
+        app_id = session.source_app_user_model_id
+
+        output[app_id] = {
+            "title": props.title or "unknown",
+            "artist": props.artist or "unknown",
+            "album_title": props.album_title or "unknown",
+        }
+    
+    return json.dumps(output)
+
+@mcp.tool("pause")
+async def pause(app_id: str) -> str:
+    """Pause the media playback for a given app_id using windows media control API."""
+
+    manager_op: IAsyncOperation[MediaManager] = \
+    MediaManager.request_async()
+    manager: MediaManager = await manager_op
+
+    sessions = manager.get_sessions()
+    for session in sessions:
+        if session.source_app_user_model_id.lower() == app_id.lower():
+            playback_info = session.get_playback_info()
+            if playback_info.controls.is_pause_enabled:
+                await session.try_pause_async()
+                return "Paused"
+            else:
+                return "Pause not available"
+            
+    return "Session not found"
+
+@mcp.tool("play")
+async def play(app_id: str) -> str:
+    """Play the media playback for a given app_id using windows media control API."""
+
+    manager_op: IAsyncOperation[MediaManager] = \
+    MediaManager.request_async()
+    manager: MediaManager = await manager_op
+
+    sessions = manager.get_sessions()
+    for session in sessions:
+        if session.source_app_user_model_id.lower() == app_id.lower():
+            playback_info = session.get_playback_info()
+            if playback_info.controls.is_play_enabled:
+                await session.try_play_async()
+                return "Playing"
+            else:
+                return "Play not available"
+            
+    return "Session not found"

mcp_windows/monitors.py

@@ -0,0 +1,35 @@
+import ctypes
+import win32con
+import win32gui
+
+from fastmcp import FastMCP
+
+mcp: FastMCP = FastMCP(
+    name="monitors",
+)
+
+@mcp.tool("sleep_monitors")
+async def sleep_monitors() -> str:
+    """Put all monitors to sleep."""
+    try:
+        ctypes.windll.user32.SendMessageW(
+            win32con.HWND_BROADCAST,
+            win32con.WM_SYSCOMMAND,
+            win32con.SC_MONITORPOWER,
+            2  # 2 = power off
+        )
+        return "Monitors put to sleep"
+    except Exception as e:
+        return f"Failed to sleep monitors: {type(e).__name__}: {e}"
+
+@mcp.tool("wake_monitors")
+async def wake_monitors() -> str:
+    """Wake up sleeping monitors."""
+    try:
+        # This is dumb, but moving the mouse 1px wakes monitors
+        x, y = win32gui.GetCursorPos()
+        ctypes.windll.user32.SetCursorPos(x, y + 1)
+        ctypes.windll.user32.SetCursorPos(x, y)
+        return "Monitors woken up"
+    except Exception as e:
+        return f"Failed to wake monitors: {type(e).__name__}: {e}"

mcp_windows/notifications.py

@@ -0,0 +1,38 @@
+import asyncio
+from fastmcp import FastMCP
+
+from mcp_windows.appid import APP_ID
+
+from winrt.windows.ui.notifications import ToastNotificationManager, ToastNotification
+from winrt.windows.data.xml.dom import XmlDocument
+
+mcp: FastMCP = FastMCP(
+    name="notifications",
+)
+
+@mcp.tool("send_toast")
+async def send_toast(title: str, message: str) -> str:
+    """Send a windows toast notification to the user."""
+
+
+    toast_xml_string = f"""
+    <toast>
+        <visual>
+            <binding template="ToastGeneric">
+                <text>{title}</text>
+                <text>{message}</text>
+            </binding>
+        </visual>
+    </toast>
+    """
+
+    xml_doc = XmlDocument()
+    xml_doc.load_xml(toast_xml_string)
+
+    toast = ToastNotification(xml_doc)
+
+    notifier = ToastNotificationManager.create_toast_notifier_with_id(APP_ID)
+
+    notifier.show(toast)
+
+    return "Toast notification sent"

mcp_windows/window_management.py

@@ -0,0 +1,140 @@
+import asyncio
+import json
+import win32gui
+import win32con
+import win32process
+import win32api
+import psutil
+
+from fastmcp import FastMCP
+
+mcp: FastMCP = FastMCP(
+    name="window_management"
+)
+
+def get_process_info(pid: int) -> dict:
+    try:
+        proc = psutil.Process(pid)
+        return {
+            "pid": pid,
+            "exe": proc.name(),
+        }
+    except psutil.NoSuchProcess:
+        return {
+            "pid": pid,
+            "exe": "<terminated>"
+        }
+
+@mcp.tool("get_foreground_window_info")
+async def get_foreground_window_info() -> str:
+    """Return information about the currently focused (foreground) window."""
+    hwnd = win32gui.GetForegroundWindow()
+    if hwnd == 0:
+        return json.dumps({"error": "No active window"})
+
+    _, pid = win32process.GetWindowThreadProcessId(hwnd)
+    info = get_process_info(pid)
+    info.update({
+        "hwnd": hwnd,
+        "title": win32gui.GetWindowText(hwnd),
+        "class": win32gui.GetClassName(hwnd),
+    })
+    return json.dumps(info, ensure_ascii=False)
+
+@mcp.tool("get_window_list")
+async def list_open_windows() -> str:
+    """Return a list of all top-level visible windows."""
+    windows = []
+
+    def callback(hwnd, _):
+        if win32gui.IsWindowVisible(hwnd) and win32gui.GetWindowText(hwnd):
+            _, pid = win32process.GetWindowThreadProcessId(hwnd)
+            info = get_process_info(pid)
+            info.update({
+                "hwnd": hwnd,
+                "title": win32gui.GetWindowText(hwnd),
+                "class": win32gui.GetClassName(hwnd),
+            })
+            windows.append(info)
+
+    win32gui.EnumWindows(callback, None)
+    return json.dumps(windows, ensure_ascii=False)
+
+@mcp.tool("focus_window")
+async def focus_window(hwnd: int) -> str:
+    """Force focus a window using all known safe tricks (thread attach, fake input, fallback restore)."""
+    try:
+        hwnd = int(hwnd)
+
+        if not win32gui.IsWindow(hwnd):
+            return "Invalid HWND"
+
+        # Step 1: Only restore if minimized (prevent resizing)
+        if win32gui.IsIconic(hwnd):
+            win32gui.ShowWindow(hwnd, win32con.SW_RESTORE)
+
+        # Step 2: Try normal focus via thread attach
+        fg_hwnd = win32gui.GetForegroundWindow()
+        fg_thread = win32process.GetWindowThreadProcessId(fg_hwnd)[0]
+        current_thread = win32api.GetCurrentThreadId()
+
+        if fg_thread != current_thread:
+            win32process.AttachThreadInput(fg_thread, current_thread, True)
+
+        try:
+            win32gui.SetForegroundWindow(hwnd)
+        except Exception:
+            pass
+
+        if fg_thread != current_thread:
+            win32process.AttachThreadInput(fg_thread, current_thread, False)
+
+        # Step 3: Check if it worked
+        if win32gui.GetForegroundWindow() == hwnd:
+            return "Focused window successfully"
+
+        # Step 4: Fallback — simulate user input (to defeat foreground lock)
+        win32api.keybd_event(0, 0, 0, 0)
+        await asyncio.sleep(0.05)
+
+        # Step 5: Try again
+        try:
+            win32gui.SetForegroundWindow(hwnd)
+        except Exception:
+            pass
+
+        if win32gui.GetForegroundWindow() == hwnd:
+            return "Focused window (after simulating input)"
+
+        # Step 6: Hard fallback — minimize + restore
+        win32gui.ShowWindow(hwnd, win32con.SW_MINIMIZE)
+        await asyncio.sleep(0.2)
+        win32gui.ShowWindow(hwnd, win32con.SW_RESTORE)
+        win32gui.SetForegroundWindow(hwnd)
+
+        if win32gui.GetForegroundWindow() == hwnd:
+            return "Focused window (after minimize/restore trick)"
+
+        return "Could not focus window: OS restrictions"
+
+    except Exception as e:
+        return f"Could not focus window: {type(e).__name__}: {e}"
+
+
+@mcp.tool("close_window")
+async def close_window(hwnd: int) -> str:
+    """Close the specified window."""
+    try:
+        win32gui.PostMessage(hwnd, win32con.WM_CLOSE, 0, 0)
+        return "Closed window"
+    except Exception as e:
+        return f"Could not close window: {type(e).__name__}: {e}"
+
+@mcp.tool("minimize_window")
+async def minimize_window(hwnd: int) -> str:
+    """Minimize the specified window."""
+    try:
+        win32gui.ShowWindow(hwnd, win32con.SW_MINIMIZE)
+        return "Minimized window"
+    except Exception as e:
+        return f"Could not minimize window: {type(e).__name__}: {e}"

mcp_windows-0.0.1.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: mcp-windows
+Version: 0.0.1
+Summary: Add your description here
+Author-email: TerminalMan <84923604+SecretiveShell@users.noreply.github.com>
+Requires-Python: >=3.13
+Requires-Dist: fastmcp>=2.2.0
+Requires-Dist: mcp>=1.6.0
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: pywin32>=310
+Requires-Dist: winrt-runtime>=3.1.0
+Requires-Dist: winrt-windows-data-xml-dom>=3.1.0
+Requires-Dist: winrt-windows-foundation-collections>=3.1.0
+Requires-Dist: winrt-windows-foundation>=3.1.0
+Requires-Dist: winrt-windows-media-control>=3.1.0
+Requires-Dist: winrt-windows-ui-notifications>=3.1.0
+Description-Content-Type: text/markdown
+
+# mcp-windows
+
+MCP server for the windows API.
+
+## Installation
+
+add this to your claude mcp config:
+
+```json
+{
+  "mcpServers": {
+    "windows": {
+      "command": "uvx",
+      "args": [
+        "mcp-windows"
+      ]
+    }
+  }
+}
+
+or locally:
+
+```json
+{
+  "mcpServers": {
+    "windows": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "C:\\Users\\{name}\\Documents\\mcp-windows",
+        "run",
+        "mcp-windows"
+      ]
+    }
+  }
+}
+```
+
+## Features
+
+### Media
+
+- get_media_sessions
+- pause
+- play
+
+### Notifications
+
+- send_toast
+
+### Window Management
+
+- get_foreground_window_info
+- get_window_list
+- focus_window
+- close_window
+- minimize_window
+
+### Monitors
+
+- sleep_monitors
+- wake_monitors
+
+## License
+
+MIT

mcp_windows-0.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+mcp_windows/__init__.py,sha256=csYpM8A238IdEljN4FLTcQUFLfNDM7xOAI4ZlyyMTrY,75
+mcp_windows/appid.py,sha256=gJN9Ug4S-mdZkpe1447_E7N33pzhPiKnR24dIHMHyZo,1201
+mcp_windows/main.py,sha256=p8MddWAGvZfhgLu_lklzfqfC2f9qbC6FsCWWSKIOqzk,648
+mcp_windows/media.py,sha256=Kf8bvNpd15kt3yZQJ8hUKnGl0ZLq2lg4ximZZZHPpX8,2518
+mcp_windows/monitors.py,sha256=ffFMvp6qEEd84wyPKrEipNSfL81jLAOPPYMORF5wBug,1037
+mcp_windows/notifications.py,sha256=UPsqsmiOvIVak4BC6ol6SrcSl1IC17oGo7h4oXluRO8,940
+mcp_windows/window_management.py,sha256=j_aNIdviNf75xZAPP0DacDAokjUrz17bFRQ_iXa-6sQ,4515
+mcp_windows-0.0.1.dist-info/METADATA,sha256=IQtr3HerrCvSZiefDETiQIpx_S7Dym7Z-ljKEisj9NE,1380
+mcp_windows-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_windows-0.0.1.dist-info/entry_points.txt,sha256=aTryo6W9hFBSP_7zE0aL0IWlIJ2eDJX7d4qIqHQ76W4,49
+mcp_windows-0.0.1.dist-info/RECORD,,

mcp_windows-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_windows-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-windows = mcp_windows:main