### Setup Pre-commit Hooks

Source: https://github.com/wandereee/windows-mcp/blob/main/CONTRIBUTING.md

Installs and sets up pre-commit hooks for automated code quality checks before each commit. Requires pip.

```bash
pip install pre-commit
pre-commit install

```

--------------------------------

### Start Windows-MCP Server with Stdio Transport (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Initializes and runs the Windows-MCP server using the FastMCP framework with stdio transport. This setup is typically used for direct integration with clients like Claude Desktop. It includes lifespan management for startup and shutdown tasks.

```python
from fastmcp import FastMCP
from contextlib import asynccontextmanager
from live_inspect.watch_cursor import WatchCursor
import asyncio

watch_cursor = WatchCursor()

@asynccontextmanager
async def lifespan(app: FastMCP):
    """Runs initialization code before server starts and cleanup after shutdown."""
    try:
        watch_cursor.start()
        await asyncio.sleep(1)  # Startup latency
        yield
    finally:
        watch_cursor.stop()

mcp = FastMCP(
    name='windows-mcp',
    instructions='Windows MCP server provides tools to interact with Windows desktop',
    lifespan=lifespan
)

# Run with stdio transport (default for Claude Desktop integration)
mcp.run(transport='stdio')
```

--------------------------------

### Launch Applications from Start Menu

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Launches applications using PowerShell commands. It supports launching standard executables (like notepad.exe) and Windows Store apps (identified by their App ID).

```python
from src.desktop import Desktop
import subprocess

desktop = Desktop()

# Get all available apps from Start Menu
apps_map = desktop.get_apps_from_start_menu()
# Returns: {'notepad': 'notepad.exe', 'calculator': 'Microsoft.WindowsCalculator_8wekyb3d8bbwe!App', ...}

# Launch standard executable
app_name = "notepad"
app_id = "notepad.exe"
result = subprocess.run(
    ['powershell', '-NoProfile', '-Command', f'Start-Process "{app_id}"'],
    capture_output=True, check=True, text=True, encoding='utf-8'
)
# Returns: ("Launched Notepad. Wait for the app to launch...", 0)

# Launch Windows Store app
app_name = "calculator"
app_id = "Microsoft.WindowsCalculator_8wekyb3d8bbwe!App"
result = subprocess.run(
    ['powershell', '-NoProfile', '-Command', f'Start-Process "shell:AppsFolder\{app_id}"'],
    capture_output=True, check=True, text=True, encoding='utf-8'
)
# Returns: ("Launched Calculator. Wait for the app to launch...", 0)
```

--------------------------------

### Launch Application via Fuzzy Matching (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Uses fuzzywuzzy to match a user-provided application name against a map of installed apps and launches the best match. Depends on the Desktop abstraction for command execution. Returns a status message indicating success or failure.

```Python
user_input = "calc"  # User types "calc" instead of "calculator"
matched_app = process.extractOne(user_input, apps_map, score_cutoff=60)

if matched_app:
    app_id, score, app_name = matched_app
    # Launch the matched app
    if app_id.endswith('.exe'):
        response, status = desktop.execute_command(f'Start-Process "{app_id}"')
    else:
        response, status = desktop.execute_command(f'Start-Process "shell:AppsFolder\\{app_id}"')
    # Returns: ("Launched Calculator. Wait for the app to launch...", 0)
else:
    # No match found
    available = list(apps_map.keys())[:5]
    # Returns: (f"Application {user_input} not found. Available apps: {available}", 1)
```

--------------------------------

### Install Windows-MCP CLI extensions via npm

Source: https://github.com/wandereee/windows-mcp/blob/main/README.md

Installs the required npm packages for Claude Desktop, Gemini CLI, Qwen Code, and Codex CLI. Node.js and npm must be available on the system. The commands globally install the CLI tools, which may require administrative privileges. After installation, the tools can be used to integrate Windows-MCP with AI assistants.

```shell
npm install -g @anthropic-ai/dxt
```

```shell
npm install -g @google/gemini-cli
```

```shell
npm install -g @qwen-code/qwen-code@latest
```

```shell
npm install -g @openai/codex
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/wandereee/windows-mcp/blob/main/CONTRIBUTING.md

Clones the Windows-MCP repository and installs the package with development and search dependencies. Requires Git and Python 3.13+.

```bash
git clone https://github.com/YOUR_USERNAME/windows-MCP.git
cd windows-mcp
pip install -e ".[dev,search]"

```

--------------------------------

### Start Windows-MCP Server with SSE Transport (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Sets up and runs the Windows-MCP server with Server-Sent Events (SSE) transport for remote connections. This script uses the `click` library for command-line arguments to specify transport type, host, and port.

```python
import click
from fastmcp import FastMCP

mcp = FastMCP(name='windows-mcp')

@click.command()
@click.option("--transport", type=click.Choice(['stdio', 'sse']), default='stdio')
@click.option("--host", default="localhost", type=str)
@click.option("--port", default=8000, type=int)
def main(transport, host, port):
    if transport == 'stdio':
        mcp.run(transport='stdio')
    else:
        mcp.run(transport='sse', host=host, port=port)

if __name__ == "__main__":
    main()

# Command line usage:
# python main.py --transport sse --host 0.0.0.0 --port 8080
```

--------------------------------

### Python Function Docstring Example (Google Style)

Source: https://github.com/wandereee/windows-mcp/blob/main/CONTRIBUTING.md

Demonstrates the Google-style docstring format for Python functions, including arguments, return values, and exceptions. Adheres to PEP 8 naming conventions and type hinting.

```python
def function_name(param1: type, param2: type) -> return_type:
    """Short description.

    Longer description if needed.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value

    Raises:
        ExceptionType: When and why this exception is raised
    """

```

--------------------------------

### Clone Windows-MCP repository

Source: https://github.com/wandereee/windows-mcp/blob/main/README.md

Uses Git to clone the Windows-MCP project from GitHub and navigates into the repository directory. Requires Git to be installed. This prepares the source files needed for all subsequent configuration steps.

```shell
git clone https://github.com/CursorTouch/Windows-MCP.git
cd Windows-MCP
```

--------------------------------

### Perform Double and Right Mouse Clicks

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Automates double-left clicks to open files and right-clicks to open context menus. It also includes an example for a less common middle-click.

```python
import pyautogui as pg
from src.desktop import Desktop

desktop = Desktop()

# Double-click to open a file
x, y = 250, 300
pg.moveTo(x, y)
control = desktop.get_element_under_cursor()
parent = control.GetParentControl()

if parent.Name == "Desktop":
    pg.click(x=x, y=y, button='left', clicks=2)
else:
    pg.mouseDown()
    pg.click(button='left', clicks=2)
    pg.mouseUp()
# Returns: "Double left Clicked on Document.txt Element with ControlType ListItemControl at (250,300)."

# Right-click to open context menu
x, y = 300, 350
pg.moveTo(x, y)
pg.click(x=x, y=y, button='right', clicks=1)
# Returns: "Single right Clicked on Folder Element with ControlType TreeItemControl at (300,350)."

# Middle-click (less common)
x, y = 400, 200
pg.click(x=x, y=y, button='middle', clicks=1)
# Returns: "Single middle Clicked on Tab Element with ControlType TabItemControl at (400,200)."
```

--------------------------------

### Switch to Application Window using Fuzzy Matching (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Builds a map of currently open applications and switches to a target window identified via fuzzy matching. Utilizes pyautogui for Alt+Tab navigation and uiautomation to restore minimized windows. Provides status messages for the performed action.

```Python
from src.desktop import Desktop
from fuzzywuzzy import process
import pyautogui as pg
import uiautomation as ua

desktop = Desktop()

# Get current desktop state
desktop_state = desktop.get_state()

# Create map of open apps
apps = {
    app.name: app
    for app in [desktop_state.active_app] + desktop_state.apps
    if app is not None
}

# Switch to specific app using fuzzy matching
target_name = "notepad"
matched_app = process.extractOne(target_name, list(apps.keys()))

if matched_app:
    app_name, score = matched_app
    app = apps[app_name]

    # If minimized, restore window
    if ua.IsIconic(app.handle):
        ua.ShowWindow(app.handle, cmdShow=9)
        # Returns: ("Notepad restored from minimized state.", 0)
    else:
        # Use Alt+Tab to switch
        shortcut = ['alt', 'tab']
        for current_app in apps.values():
            if current_app.name == app_name:
                break
            pg.hotkey(*shortcut)
            pg.sleep(0.1)
        # Returns: ("Switched to Notepad window.", 0)
```

--------------------------------

### Configure Windows-MCP server in JSON settings

Source: https://github.com/wandereee/windows-mcp/blob/main/README.md

Adds a server configuration block to the JSON settings files used by Claude Desktop, Gemini CLI, and Qwen Code. The configuration tells each tool to run the MCP server with UV, pointing to the repository directory. Place the JSON snippet in the appropriate settings file for the respective tool.

```json
{
  "command": "uv",
  "args": [
    "--directory",
    "<path to the windows-mcp directory>",
    "run",
    "main.py"
  ]
}
```

```json
{
  "theme": "Default",
  "...": "",
  //MCP Server Config
  "mcpServers": {
    "windows-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<path to the windows-mcp directory>",
        "run",
        "main.py"
      ]
    }
  }
}
```

```json
{
  //MCP Server Config
  "mcpServers": {
    "windows-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<path to the windows-mcp directory>",
        "run",
        "main.py"
      ]
    }
  }
}
```

--------------------------------

### Configure Windows-MCP server in TOML for Codex CLI

Source: https://github.com/wandereee/windows-mcp/blob/main/README.md

Adds a TOML configuration entry for the Codex CLI to run the Windows-MCP server using UV. Insert the snippet into the `config.toml` file located in `%USERPROFILE%/.codex/`. This enables Codex to launch the MCP server with the specified directory and command.

```toml
[mcp_servers.windows-mcp]
command="uv"
args=[
  "--directory",
  "<path to the windows-mcp directory>",
  "run",
  "main.py"
]
```

--------------------------------

### Capture Desktop State with Annotated Screenshot (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Captures the Windows desktop state along with a screenshot that includes annotations for UI elements. This is intended for use with vision-aware AI models. The screenshot is returned as PNG bytes.

```python
from src.desktop import Desktop
from fastmcp.utilities.types import Image

desktop = Desktop()

# Get desktop state with visual screenshot (use_vision=True)
desktop_state = desktop.get_state(use_vision=True)

# Screenshot is returned as PNG bytes with UI elements labeled
screenshot_bytes = desktop_state.screenshot

# Create Image object for MCP response
image = Image(data=screenshot_bytes, format='png')

# Combined response with text and image
response = [
    f"Focused App: {desktop_state.active_app_to_string()}\n"
    f"Interactive Elements: {desktop_state.tree_state.interactive_elements_to_string()}",
    image
]

# The screenshot includes bounding boxes and labels for interactive elements
# making it easy for vision models to understand the UI context
```

--------------------------------

### web content scraping and markdown conversion

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Fetches a webpage and converts its HTML to Markdown using requests + markdownify for analysis without rendering.

```python
import requests
from markdownify import markdownify as md

url = "https://example.com"
response = requests.get(url, timeout=10)
html = response.text
content = md(html=html)

```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/wandereee/windows-mcp/blob/main/CONTRIBUTING.md

Executes the test suite using pytest. Can be used to run all tests or specific directories.

```bash
pytest
pytest tests/

```

--------------------------------

### Resize and Move Application Window (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Resizes a given window to a specific width and height and moves it to a defined screen position. Relies on uiautomation's ControlFromHandle to manipulate the window. Returns a confirmation message upon success.

```Python
from src.desktop import Desktop
from uiautomation import ControlFromHandle

desktop = Desktop()

# Get desktop state
desktop_state = desktop.get_state()
active_app = desktop_state.active_app

if active_app:
    app_control = ControlFromHandle(active_app.handle)

    # Resize window to 1024x768 at position (100, 100)
    x, y = 100, 100
    width, height = 1024, 768
    app_control.MoveWindow(x, y, width, height)
    # Returns: ("Application Notepad resized to 1024x768 at 100,100.", 0)
```

--------------------------------

### powershell command execution (from python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Executes PowerShell commands using Python's subprocess, ensuring UTF-8 output and capturing stdout/stderr. Demonstrates process listing and basic file operations (mkdir, listing users).

```python
import subprocess
import os

command = "Get-Process | Where-Object {$_.Name -eq 'notepad'} | Select-Object Name, CPU"
result = subprocess.run(
    ['powershell', '-NoProfile', '-Command',
     '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; ' + command],
    capture_output=True,اسات‌خان‌بی سیزە.‌ و, حاکمیت, گزارش‌های سازمان, تأثیر, و پیروزی‌ها, بی‌عدالتی, جامعه, و اصلاح‌های ممکن.
```

--------------------------------

### Copy Text to Clipboard using Pyperclip (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Copies a predefined string to the system clipboard using the pyperclip library. No additional dependencies beyond pyperclip are required. The snippet demonstrates a simple way to programmatically set clipboard contents.

```Python
import pyperclip as pc

# Copy text to system clipboard
text = "Important data to copy"
pc.copy(text)
```

--------------------------------

### Capture Desktop State without Vision (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Retrieves the current state of the Windows desktop without using visual analysis. It extracts information about active and opened applications, as well as interactive and informative UI elements. The output is string-based.

```python
from src.desktop import Desktop

desktop = Desktop()

# Get desktop state including apps, UI elements, and accessible information
desktop_state = desktop.get_state(use_vision=False)

# Extract interactive elements (buttons, text fields, etc.)
interactive_elements = desktop_state.tree_state.interactive_elements_to_string()
# Output format: "Label: 0 App Name: Notepad ControlType: Button Control Name: Save Shortcut: Ctrl+S Cordinates: (100,150)"

# Extract informative elements (text, labels, status)
informative_elements = desktop_state.tree_state.informative_elements_to_string()
# Output format: "App Name: Calculator Name: Result Display"

# Extract scrollable areas
scrollable_elements = desktop_state.tree_state.scrollable_elements_to_string()
# Output format: "Label: 15 App Name: Chrome ControlType: Document Control Name: Webpage Cordinates: (640,480) Horizontal Scrollable: False Vertical Scrollable: True"

# Get focused and opened apps
active_app = desktop_state.active_app_to_string()
# Output format: "Name: Notepad Depth: 0 Status: Normal Size: (800,600)"

opened_apps = desktop_state.apps_to_string()
# Output format: "Name: Calculator Depth: 1 Status: Minimized Size: (400,300)"

print(f"Active: {active_app}\nOpened: {opened_apps}\nInteractive: {interactive_elements}")
```

--------------------------------

### Type ASCII Text into Input Field

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Simulates typing ASCII text into an input field. It first clicks the target field and then uses `pyautogui.typewrite` for input with a specified interval.

```python
import pyautogui as pg
import pyperclip as pc

# Click on text field first
x, y = 200, 100
pg.click(x=x, y=y)

# Type ASCII text using typewrite
text = "Hello World"
pg.typewrite(text, interval=0.1)

# Returns: "Typed Hello World on Search Box Element with ControlType EditControl at (200,100)."
```

--------------------------------

### copy text to clipboard (pyperclip)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Copies a string into the system clipboard using pyperclip. Useful for automated copying from Python to other apps. Ensure the OS clipboard is available.

```python
import pyperclip as pc

pc.copy('Copied text')
clipboard_content = pc.paste()

```

--------------------------------

### execution delays (pyautogui sleep)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Introduces a scripted delay with pyautogui.sleep for pacing actions (e.g., wait for app load or page render).

```python
import pyautogui as pg
pg.sleep(2)
pg.sleep(5)

```

--------------------------------

### retrieve text from clipboard (pyperclip)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Retrieves the current text in the system clipboard via pyperclip. If the clipboard is empty or contains non-text data, returns an empty string.

```python
import pyperclip as pc
clipboard_content = pc.paste()

```

--------------------------------

### Drag and Drop Elements via PyAutoGUI (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Performs a drag-and-drop operation from a source coordinate to a destination coordinate using pyautogui, then retrieves information about the element under the cursor. Useful for automating file moves or UI interactions. Returns a descriptive message of the performed drag.

```Python
import pyautogui as pg
from src.desktop import Desktop

desktop = Desktop()

# Drag file from source to destination
from_x, from_y = 200, 300  # Source coordinates
to_x, to_y = 500, 400      # Destination coordinates

# Perform drag operation with 0.5 second duration
pg.drag(from_x, from_y, to_x, to_y, duration=0.5)

# Get element information at final position
control = desktop.get_element_under_cursor()
# Returns: "Dragged Document.txt element with ControlType ListItemControl from (200,300) to (500,400)."
```

--------------------------------

### keyboard operations (pyautogui hotkeys + key presses)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Performs common keyboard actions with pyautogui: pressing hotkey combinations (e.g., ctrl+c, alt+tab) and single key presses (enter, escape, arrows, function keys).

```python
import pyautogui as pg
pg.hotkey('ctrl', 'c')
pg.hotkey('alt', 'tab')
pg.hotkey('win', 'r')
pg.hotkey('ctrl', 'shift', 'esc')
pg.press('enter')
pg.press('escape')
pg.press('down')
pg.press('up')
pg.press('left')
pg.press('right')
pg.press('f1')
pg.press('f5')
pg.press('f11')
pg.press('backspace')
pg.press('delete')
pg.press('tab')
pg.press('space')

```

--------------------------------

### Perform Single Left Mouse Click

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Simulates a single left mouse click on a UI element at specified coordinates. It differentiates behavior for desktop elements versus elements within windows and retrieves element information.

```python
import pyautogui as pg
from src.desktop import Desktop

desktop = Desktop()

# Click coordinates obtained from State-Tool output
x, y = 100, 150
pg.moveTo(x, y)

# Get element information under cursor
control = desktop.get_element_under_cursor()
parent = control.GetParentControl()

# Perform click - different behavior for desktop vs windowed elements
if parent.Name == "Desktop":
    pg.click(x=x, y=y, button='left', clicks=1)
else:
    pg.mouseDown()
    pg.click(button='left', clicks=1)
    pg.mouseUp()

# Returns: "Single left Clicked on Save Button Element with ControlType ButtonControl at (100,150)."
```

--------------------------------

### Resize Application Window While Preserving Position (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Adjusts only the size of a window while keeping its current screen coordinates unchanged. Uses the window's bounding rectangle to retrieve its existing position. Provides a status message describing the resize operation.

```Python
from src.desktop import Desktop
from uiautomation import ControlFromHandle

desktop = Desktop()
desktop_state = desktop.get_state()
active_app = desktop_state.active_app

if active_app:
    app_control = ControlFromHandle(active_app.handle)

    # Keep current position
    current_x = app_control.BoundingRectangle.left
    current_y = app_control.BoundingRectangle.top

    # Change only size
    new_width, new_height = 800, 600
    app_control.MoveWindow(current_x, current_y, new_width, new_height)
    # Returns: ("Application Calculator resized to 800x600 at 250,150.", 0)
```

--------------------------------

### Type Non-ASCII Text Using Clipboard

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Handles typing non-ASCII characters (like Chinese or Japanese) by copying the text to the clipboard and then pasting it using a keyboard shortcut. It includes saving and restoring the original clipboard content.

```python
import pyautogui as pg
import pyperclip as pc

# Click on text field
x, y = 300, 150
pg.click(x=x, y=y)

# For non-ASCII characters (Chinese, Japanese, etc.), use clipboard
text = "你好世界"  # Chinese characters
original_clipboard = pc.paste()  # Save current clipboard

try:
    pc.copy(text)
    pg.sleep(0.1)
    pg.hotkey('ctrl', 'v')  # Paste using keyboard shortcut
finally:
    pg.sleep(0.1)
    pc.copy(original_clipboard)  # Restore original clipboard

# Returns: "Typed 你好世界 on Text Input Element with ControlType EditControl at (300,150)."
```

--------------------------------

### Perform Vertical Scrolling at Coordinates (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Moves the mouse cursor to a specified screen location and performs vertical scrolling using uiautomation's wheel functions. Supports both scrolling down and up with configurable wheel counts. Returns textual messages indicating the scroll actions performed.

```Python
import pyautogui as pg
import uiautomation as ua

# Scroll down at specific location
x, y = 640, 480
pg.moveTo(x, y)

# Scroll down 5 wheel times (approximately 15-25 lines)
wheel_times = 5
ua.WheelDown(wheel_times)
# Returns: "Scrolled vertical down by 5 wheel times."

# Scroll up 3 wheel times
wheel_times = 3
ua.WheelUp(wheel_times)
# Returns: "Scrolled vertical up by 3 wheel times."
```

--------------------------------

### Clear Text and Type New Content

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Clears existing text from an input field by selecting all content and deleting it, then types new content. Optionally, it can press Enter after typing.

```python
import pyautogui as pg

x, y = 250, 200
pg.click(x=x, y=y)

# Clear existing text first
pg.hotkey('ctrl', 'a')  # Select all
pg.press('backspace')  # Delete

# Type new text
text = "New content"
pg.typewrite(text, interval=0.1)

# Optionally press Enter
pg.press('enter')

# Returns: "Typed New content on Address Bar Element with ControlType EditControl at (250,200)."
```

--------------------------------

### Horizontal Scrolling Using Shift Modifier (Python)

Source: https://context7.com/wandereee/windows-mcp/llms.txt

Executes horizontal scrolling by holding the Shift key while using the mouse wheel. Moves the cursor to a target location before scrolling and releases the key afterward. Provides messages indicating the direction and amount of scrolling.

```Python
import pyautogui as pg
import uiautomation as ua

# Horizontal scroll right
x, y = 500, 400
pg.moveTo(x, y)

pg.keyDown('Shift')
pg.sleep(0.05)
wheel_times = 3
ua.WheelDown(wheel_times)  # With Shift pressed = scroll right
pg.sleep(0.05)
pg.keyUp('Shift')
# Returns: "Scrolled horizontal right by 3 wheel times."

# Horizontal scroll left
pg.keyDown('Shift')
pg.sleep(0.05)
wheel_times = 2
ua.WheelUp(wheel_times)  # With Shift pressed = scroll left
pg.sleep(0.05)
pg.keyUp('Shift')
# Returns: "Scrolled horizontal left by 2 wheel times."
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.