### Verify Installation

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

Run the main script with the --help flag to verify the installation.

```bash
uv run main.py --help
```

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

### Install windows-mcp

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

Install the windows-mcp package using pip. This is the first step to get started with the tool.

```bash
pip install windows-mcp
```

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

### Install Qwen Code CLI

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

Installs the Qwen Code CLI globally. Ensure you have Node.js and npm installed.

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

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

### Configuration File Example

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

Example TOML configuration file for ~/.windows-mcp/config.toml. This file allows for persistent server and security settings.

```toml
# ~/.windows-mcp/config.toml
[server]
transport = "sse"
host = "127.0.0.1"
port = 8000
auth_key = "sk_..."

[security]
ip_allowlist = ["192.168.1.0/24"]

[tools]
exclude = ["Registry", "PowerShell"]
```

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

### Install Windows-MCP as a Background Task

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

Install the Windows-MCP server to run automatically at login.

```shell
windows-mcp install
```

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

### Local Checkout Setup for Windows-MCP Pi Extension

Source: https://github.com/cursortouch/windows-mcp/blob/main/docs/pi-integration.md

Sets up the Windows-MCP project locally for development as a Pi extension. This involves cloning the repository, synchronizing dependencies, installing npm packages, and running Pi.

```powershell
git clone https://github.com/CursorTouch/Windows-MCP.git
cd Windows-MCP
uv sync
npm install
pi
```

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

### Install Dependencies

Source: https://github.com/cursortouch/windows-mcp/blob/main/CLAUDE.md

Installs project dependencies using the UV package manager.

```bash
uv sync
```

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

### Full Example TOML Configuration

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

This is a comprehensive example of a TOML configuration file for Windows MCP, illustrating server, security, and tool settings.

```toml
# ~/.windows-mcp/config.toml

[server]
transport = "sse"
host = "127.0.0.1"
port = 8000
auth_key = "sk_test_1234567890abcdef"
ssl_certfile = "cert.pem"
ssl_keyfile = "key.pem"
stateless_http = false

[security]
ip_allowlist = [
    "192.168.1.0/24",
    "10.0.0.0/8"
]
cors_origins = [
    "https://app.example.com"
]
oauth_client_id = "windows-mcp-app"
oauth_client_secret = "secret_key_here"

[tools]
exclude = ["Registry", "PowerShell"]

```

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

### Remote Windows MCP Configuration with Security

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

Example configuration for a remote Windows MCP setup, including authentication, IP allowlisting, and TLS for secure communication. This is recommended for production environments.

```json
{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": ["windows-mcp", "serve", "--transport", "sse", "--host", "0.0.0.0"],
      "env": {
        "WINDOWS_MCP_AUTH_KEY": "your_token",
        "WINDOWS_MCP_IP_ALLOWLIST": "203.0.113.0/24",
        "WINDOWS_MCP_SSL_CERTFILE": "/path/to/cert.pem",
        "WINDOWS_MCP_SSL_KEYFILE": "/path/to/key.pem"
      }
    }
  }
}
```

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

### Example Tools Configuration via CLI

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Shows how to exclude or explicitly enable tools using command-line arguments.

```bash
windows-mcp serve --exclude-tools PowerShell,Registry
windows-mcp serve --tools Snapshot,Click,Type

```

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

### Example Server Configuration

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Illustrates how to configure server transport, host, port, authentication, and SSL settings in a TOML file.

```toml
[server]
transport = "sse"
host = "127.0.0.1"
port = 8000
auth_key = "sk_..."
ssl_certfile = "cert.pem"
ssl_keyfile = "key.pem"
stateless_http = false

```

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

### Install Gemini CLI Globally

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

Installs the @google/gemini-cli package globally using npm. This is a prerequisite for configuring MCP server in Gemini CLI.

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

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

### Configure Claude Desktop with PyPI MCP Server

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

Adds configuration to claude_desktop_config.json to use the windows-mcp server installed via PyPI using uvx. This is the recommended option for installing from PyPI.

```json
{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp",
        "serve"
      ]
    }
  }
}
```

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

### Serve with Custom Configuration File

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Starts the Windows MCP server using a configuration file located at a specified path.

```bash
windows-mcp serve --config /etc/windows-mcp/config.toml

```

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

### TOML Basic Syntax Example

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Illustrates the basic syntax rules for TOML configuration files, including comments, key-value pairs, and sections.

```toml
# Comment
key = value                    # String
key = 123                      # Integer
key = true                     # Boolean
key = ["item1", "item2"]       # Array of strings

[section]                      # Section header
section_key = "section_value"

```

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

### Example Tools Configuration

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Demonstrates how to exclude specific tools or specify an explicit list of enabled tools using a TOML file.

```toml
[tools]
exclude = ["Registry", "PowerShell"]

```

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

### Serve with Explicitly Enabled Tools

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Starts the Windows MCP server and enables only a specified list of tools.

```bash
windows-mcp serve --tools Snapshot,Click,Type,Screenshot

```

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

### Install Windows MCP with SSE Transport

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

Installs the windows-mcp server using the SSE transport and binds it to a specific host and port. This is a direct installation command.

```shell
windows-mcp install --transport sse --host 127.0.0.1 --port 8000
```

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

### Claude Desktop MCP Server Configuration

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

Example JSON configuration for Claude Desktop to connect to a Windows-MCP server using HTTP and OAuth. Ensure the URL and OAuth details match your server setup.

```json
{
  "mcpServers": {
    "windows-mcp": {
      "type": "http",
      "url": "https://<host>:8000/mcp/",
      "oauth": {
        "clientId": "my-client",
        "clientSecret": "my-secret"
      }
    }
  }
}
```

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

### Install uv on Windows

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

Installs the uv package manager on Windows using a PowerShell script. This is required for running MCP servers from WSL.

```powershell
irm https://astral.sh/uv/install.ps1 | iex
```

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

### Install Codex CLI

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

Installs the Codex CLI globally. Requires Node.js and npm.

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

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

### Example Security Configuration

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Shows how to define IP allowlists, CORS origins, and OAuth credentials within a TOML configuration file.

```toml
[security]
ip_allowlist = [
    "192.168.1.0/24",
    "10.0.0.5",
    "::1"  # IPv6
]
cors_origins = [
    "https://client.example.com",
    "https://app.example.com"
]
oauth_client_id = "my_client_id"
oauth_client_secret = "my_secret"

```

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

### Install Windows-MCP Pi Package

Source: https://github.com/cursortouch/windows-mcp/blob/main/docs/pi-integration.md

Installs the Windows-MCP package globally using Pi. This command fetches the package directly from the GitHub repository.

```powershell
pi install git:github.com/CursorTouch/Windows-MCP
```

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

### Install Claude Code CLI

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

Installs the Claude Code CLI globally. Requires Node.js and npm.

```shell
npm install -g @anthropic-ai/claude-code
```

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

### Run MCP Server

Source: https://github.com/cursortouch/windows-mcp/blob/main/CLAUDE.md

Starts the Windows-MCP server using the UV run command.

```bash
uv run windows-mcp
```

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

### Serve with IP Allowlist

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Starts the Windows MCP server and restricts access to specified IP addresses or ranges.

```bash
windows-mcp serve --ip-allowlist "192.168.1.0/24,10.0.0.5"

```

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

### Example TOML Configuration File

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/infrastructure-and-security.md

This TOML file demonstrates the structure for server, security, and tools configurations, including transport settings, authentication keys, IP allowlists, CORS origins, and tool exclusions.

```toml
[server]
transport = "sse"
host = "127.0.0.1"
port = 8000
auth_key = "sk_..."

[security]
ip_allowlist = ["192.168.1.0/24"]
cors_origins = ["https://app.example.com"]

[tools]
exclude = ["Registry", "PowerShell"]
```

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

### Serve with Stdio Transport

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Starts the Windows MCP server using the default stdio transport.

```bash
windows-mcp serve

```

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

### Streamable HTTP POST Request Example

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/endpoints.md

Example of how to send an MCP command via POST request to the Streamable HTTP transport endpoint. Ensure correct headers and JSON-RPC body are used.

```bash
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_..." \
  -d '{"jsonrpc":"2.0", "id":"1", "method":"tools/call", "params":{"name":"Screenshot", "arguments":{}}}'
```

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

### Serve with Debug Mode Enabled

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Starts the Windows MCP server with debug logging enabled for troubleshooting.

```bash
windows-mcp serve --debug

```

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

### Install MCPB Package Globally

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

Installs the @anthropic-ai/mcpb package globally using npm. This is a prerequisite for configuring MCP server in Claude Desktop.

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

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

### Serve with Streamable HTTP and TLS

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Starts the Windows MCP server using streamable HTTP transport with TLS enabled, requiring certificate and key files.

```bash
windows-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000 \
  --ssl-certfile cert.pem --ssl-keyfile key.pem

```

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

### Serve with SSE Transport and Auth

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Starts the Windows MCP server with SSE transport, specifying host, port, and authentication key.

```bash
windows-mcp serve --transport sse --host 127.0.0.1 --port 8000 --auth-key "sk_test_..."

```

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

### Configure Perplexity Desktop with Source MCP Server

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

Configuration for Perplexity Desktop to use the windows-mcp server installed from source using uv. Requires specifying the local directory path.

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

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

### Clone Windows-MCP Repository

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

Clones the Windows-MCP repository from GitHub. This is the first step for installing the MCP server from source.

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

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

### Enable Authentication for Windows-MCP

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

Starts the Windows-MCP service with SSE transport and an authentication key. Requests must include an 'Authorization: Bearer your_token' header.

```shell
windows-mcp serve --transport sse --host 0.0.0.0 --auth-key "your_token"
```

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

### Run windows-mcp Server

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

Start the windows-mcp server with different transport and security configurations. The default is stdio, suitable for Claude Desktop.

```bash
# Stdio (default, for Claude Desktop)
windows-mcp serve
```

```bash
# SSE with auth
windows-mcp serve --transport sse --host 127.0.0.1 --auth-key sk_...
```

```bash
# HTTP with TLS
windows-mcp serve --transport streamable-http --host 0.0.0.0 \
  --ssl-certfile cert.pem --ssl-keyfile key.pem
```

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

### Serve Excluding Specific Tools

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Starts the Windows MCP server while excluding certain tools from being available.

```bash
windows-mcp serve --exclude-tools PowerShell,Registry,Process

```

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

### Configure Claude Desktop with Source MCP Server

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

Adds configuration to claude_desktop_config.json to use the windows-mcp server installed from source using uv. Requires specifying the local directory path.

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

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

### Run Windows-MCP Pi Extension Without Installation

Source: https://github.com/cursortouch/windows-mcp/blob/main/docs/pi-integration.md

Executes the Windows-MCP extension from its GitHub repository without a formal installation. Useful for testing or temporary use.

```powershell
pi -e git:github.com/CursorTouch/Windows-MCP
```

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

### Bearer Token Authentication Example

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/endpoints.md

Include this Authorization header in your requests when using a Bearer token for authentication.

```bash
curl -H "Authorization: Bearer sk_test_abc123" http://localhost:8000/mcp/
```

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

### Configure Windows-MCP with TLS/HTTPS

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

Starts the Windows-MCP service using provided TLS certificate and key files for secure HTTPS connections.

```shell
windows-mcp serve --ssl-certfile cert.pem --ssl-keyfile key.pem
```

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

### Configure Gemini CLI with PyPI MCP Server

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

Adds configuration to %USERPROFILE%/.gemini/settings.json to use the windows-mcp server installed via PyPI using uvx. Includes other potential settings like theme.

```json
{
  "theme": "Default",
  ...
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp",
        "serve"
      ]
    }
  }
}
```

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

### Whitelist Specific Tools in Windows-MCP

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

Starts the Windows-MCP service and enables only the specified tools. Use '--tools' for whitelisting.

```shell
windows-mcp serve --tools "Screenshot,Click,Snapshot"   # Enable only these tools
```

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

### Configure Windows-MCP for OAuth 2.0 + PKCE

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

Starts the Windows-MCP service with streamable-HTTP transport, TLS enabled, and OAuth 2.0 client credentials. This is for MCP clients that use OAuth instead of a static API key.

```shell
windows-mcp serve --transport streamable-http --host 0.0.0.0 \
  --ssl-certfile ~/.windows-mcp/cert.pem \
  --ssl-keyfile  ~/.windows-mcp/key.pem \
  --oauth-client-id my-client \
  --oauth-client-secret my-secret
```

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

### Configure IP Allowlist for Windows-MCP

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

Starts the Windows-MCP service with an authentication key and an IP allowlist. This restricts connections to specified CIDR ranges.

```shell
windows-mcp serve --auth-key "token" --ip-allowlist "203.0.113.0/24,198.51.100.5"
```

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

### Local Windows MCP Configuration

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

Example configuration for running Windows MCP locally without enhanced security settings. Useful for development or isolated environments.

```json
{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": ["windows-mcp", "serve"],
      "env": { "WINDOWS_MCP_SCREENSHOT_SCALE": "0.5" }
    }
  }
}
```

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

### Configure Claude Desktop with Source for MSIX

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

Configures Claude Desktop to use the windows-mcp server installed from source, specifying the full absolute path to uv.exe and the directory. This is for MSIX-packaged applications.

```json
{
  "mcpServers": {
    "windows-mcp": {
      "command": "C:\\Users\\<user>\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "C:\\path\\to\\Windows-MCP",
        "run",
        "windows-mcp",
        "serve"
      ]
    }
  }
}
```

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

### Configure Perplexity Desktop with PyPI MCP Server

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

Configuration for Perplexity Desktop to use the windows-mcp server installed via PyPI using uvx. This is added in the 'Advanced' connector settings.

```json
{
  "command": "uvx",
  "args": [
    "windows-mcp",
    "serve"
  ]
}
```

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

### Run Windows-MCP with Streamable HTTP Transport

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

Starts the Windows-MCP service using streamable-HTTP transport for network access. This is recommended for production environments.

```shell
uvx windows-mcp serve --transport streamable-http --host localhost --port 8000
```

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

### MultiEdit Tool: Form filling example

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/multi-tools.md

Demonstrates filling multiple form fields using coordinates and corresponding text. This is useful for automating data entry in forms.

```python
result = multi_edit_tool(
    locs=[
        [200, 100, "Alice"],      # First name
        [400, 100, "Smith"],       # Last name
        [200, 150, "alice@ex.com"] # Email
    ]
)
```

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

### Run Windows-MCP with Default Stdio Transport

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

Starts the Windows-MCP service using the default stdio transport. This is suitable for direct connections from MCP clients.

```shell
# Runs with stdio transport (default)
uvx windows-mcp serve
```

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

### JSON String Parsing Example

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/errors-and-validation.md

Demonstrates how JSON strings are parsed for multi-tool parameters like 'locs' and 'labels'. Parsing failures result in an 'Invalid JSON' error.

```json
"[[100,200], [150,250]]"
```

```json
"[5, 10, 15]"
```

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

### Semantic Tree Rendering Example

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/tree-service.md

An alternative tree format that displays the full semantic hierarchy, including nested structural and interactive elements.

```text
desktop
├── window "Explorer"
│   ├── toolbar "Standard Buttons"
│   │   ├── button "Back"
│   │   └── button "Forward"
│   └── listview "Files"
│       ├── (150, 100) listitem "folder1"
│       └── (150, 130) listitem "file1.txt"
└── window "NotePad"
```

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

### Quick Visual Snapshot

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/snapshot-screenshot-tools.md

Use this snippet to get a fast visual snapshot of the screen when UI element IDs are not required. It skips expensive UI tree extraction.

```python
# Get a fast visual snapshot
result = screenshot_tool()
```

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

### Python Function with Docstring and Type Hints

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

Example of a Python function adhering to project style guidelines, including type hints and Google-style docstrings. Ensure all public functions and classes follow this pattern.

```python
def click_tool(
    loc: list[int],
    button: Literal['left', 'right', 'middle'] = 'left',
    clicks: int = 1
) -> str:
    """Click on UI elements at specific coordinates. 
    
    Args:
        loc: List of [x, y] coordinates to click
        button: Mouse button to use (left, right, or middle)
        clicks: Number of clicks (1=single, 2=double, 3=triple)
    
    Returns:
        Confirmation message describing the action performed
    
    Raises:
        ValueError: If loc doesn't contain exactly 2 integers
    """
    if len(loc) != 2:
        raise ValueError("Location must be a list of exactly 2 integers [x, y]")
    # Implementation...

```

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

### Run Windows-MCP with SSE Transport

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

Starts the Windows-MCP service using Server-Sent Events (SSE) transport for network access. Specify host and port as needed.

```shell
# Or with SSE/Streamable HTTP for network access
uvx windows-mcp serve --transport sse --host localhost --port 8000
```

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

### Get Cursor Location

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Gets the current mouse cursor position in screen coordinates.

```python
desktop.get_cursor_location()
```

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

### Generate Auth Key and TLS Config

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

This command generates an authentication key, sets up a self-signed TLS certificate, and configures the transport for streamable HTTP. It prints an example MCP client configuration for the selected transport.

```shell
windows-mcp auth --transport streamable-http --host 0.0.0.0 --port 8000 --with-tls

```

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

### Get Clipboard Content

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/data-tools.md

Retrieves text content from the Windows clipboard. This tool is used in 'get' mode.

```python
result = clipboard_tool(mode='get')
```

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

### Generate Auth Key and Config

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

Run this command to generate an authentication key and save a working configuration to `~/.windows-mcp/config.toml`. This is a convenient way to set up basic authentication.

```shell
windows-mcp auth

```

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

### Manage Applications

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Launches, switches to, or resizes applications. Specify the mode, application name, and optionally window location and size for resize operations.

```python
desktop.app(mode="launch", name="notepad.exe")
```

```python
desktop.app(mode="switch", name="Untitled - Notepad")
```

```python
desktop.app(mode="resize", name="Untitled - Notepad", window_loc=[100, 100], window_size=[800, 600])
```

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

### Lifespan Management for Services

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/module-structure.md

Demonstrates how to manage the lifecycle of services like Analytics, Desktop, and WatchDog using an asynchronous context manager. This ensures services are initialized before the server runs and properly cleaned up during shutdown.

```python
from contextlib import asynccontextmanager

# Assume FastMCP, PostHogAnalytics, Desktop, and WatchDog are defined elsewhere
class FastMCP:
    pass

class PostHogAnalytics:
    async def close(self):
        pass

class Desktop:
    pass

class WatchDog:
    def start(self):
        pass

    def stop(self):
        pass

@asynccontextmanager
async def lifespan(app: FastMCP):
    # Startup
    analytics = PostHogAnalytics()
    desktop = Desktop()
    watchdog = WatchDog()
    watchdog.start()
    
    yield  # Server running
    
    # Shutdown
    watchdog.stop()
    await analytics.close()
```

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

### Clipboard Tool

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/data-tools.md

Gets or sets clipboard text content. Requires 'get' or 'set' mode. For 'set' mode, the text parameter is mandatory.

```APIDOC
## Clipboard Tool

Gets or sets clipboard text content.

### Signature

```python
@mcp.tool(name="Clipboard")
def clipboard_tool(
    mode: Literal["get", "set"],
    text: str | None = None,
    ctx: Context = None,
) -> str
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| mode | "get" | "set" | — | Operation mode (required) |
| text | str | None | Text to set (required for "set" mode) |
| ctx | Context | None | MCP context (injected by framework) |
```

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

### Observation Pattern with Tools

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

Python code demonstrating the observation pattern using Snapshot, Click, and Type tools. Capture desktop state, identify elements by label, and interact using labels.

```python
# Step 1: Capture desktop state
snapshot = snapshot_tool(use_vision=True, use_ui_tree=True)

# Step 2: Identify element IDs from returned tree
# Elements have labels (numeric IDs) you can reference

# Step 3: Interact using labels (no coordinates needed)
click_tool(label=42)  # Click element with label 42
type_tool(text="Hello")
```

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

### get_active_window

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Gets the currently focused window.

```APIDOC
## get_active_window()

### Description
Gets the currently focused window.

### Method
GET (conceptual)

### Parameters
#### Query Parameters
- **windows** (list[Window] | None) - Optional - Pre-enumerated windows list

### Returns
`Window` object or None if no window is focused
```

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

### get_screen_size

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Gets the total screen dimensions.

```APIDOC
## get_screen_size()

### Description
Gets the total screen dimensions.

### Method
GET (conceptual)

### Returns
`Size` with total width and height
```

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

### get_controls_handles

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Gets window handles for all top-level windows.

```APIDOC
## get_controls_handles()

### Description
Gets window handles for all top-level windows.

### Method
GET (conceptual)

### Returns
Set of window handles (HWND)
```

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

### get_cursor_location

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Gets the current mouse cursor position.

```APIDOC
## get_cursor_location()

### Description
Gets current mouse cursor position.

### Method
GET (conceptual)

### Returns
Tuple (x, y) in screen coordinates
```

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

### App Tool

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/system-tools.md

Manages application launch, window switching, and window resizing. Supports launching applications by name or path, switching to existing windows by title, and resizing the active or a specific window.

```APIDOC
## App Tool

### Description
Manages application launch, window switching, and window resizing.

### Signature
```python
app_tool(mode: Literal['launch', 'resize', 'switch'] = 'launch', name: str | None = None, window_loc: list[int] | None = None, window_size: list[int] | None = None, ctx: Context = None) -> str
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **mode** (string) - Required - Operation mode ('launch', 'resize', 'switch'). Defaults to 'launch'.
- **name** (string) - Optional - Application name/path for 'launch' mode, or window title for 'resize'/'switch'.
- **window_loc** (list[int]) - Optional - Position [x, y] for 'resize' mode.
- **window_size** (list[int]) - Optional - Size [width, height] for 'resize' mode.
- **ctx** (Context) - Optional - MCP context (injected by framework).

### Returns
String describing the operation result.

### Examples
**Launch application:**
```python
app_tool(mode='launch', name='notepad')
app_tool(mode='launch', name='chrome')
```

**Switch to window:**
```python
app_tool(mode='switch', name='Visual Studio Code')
```

**Resize active window:**
```python
app_tool(mode='resize', window_loc=[0, 0], window_size=[1920, 1080])
```

**Resize specific window:**
```python
app_tool(mode='resize', name='Notepad', window_loc=[100, 100], window_size=[800, 600])
```
```

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

### get_windows

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Enumerates visible application windows.

```APIDOC
## get_windows()

### Description
Enumerates visible application windows.

### Method
GET (conceptual)

### Parameters
#### Query Parameters
- **controls_handles** (set[int] | None) - Optional - Pre-enumerated set of handles

### Returns
Tuple of (windows list, handles set)
```

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

### Get Clipboard Text

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/data-tools.md

Retrieves the current text content from the system clipboard.

```python
text = clipboard_tool(mode='get')
```

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

### Get Screen Size

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Retrieves the total screen dimensions (width and height) of the primary display.

```python
desktop.get_screen_size()
```

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

### app

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Launches, switches, or resizes applications.

```APIDOC
## app()

### Description
Launches, switches, or resizes applications.

### Method
POST (conceptual)

### Parameters
#### Request Body
- **mode** (str) - Required - "launch", "switch", or "resize"
- **name** (str | None) - Optional - App name or window title
- **window_loc** (list[int] | None) - Optional - [x, y] for resize mode
- **window_size** (list[int] | None) - Optional - [width, height] for resize mode

### Returns
Status string
```

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

### CORS Headers Example

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/endpoints.md

When CORS origins are configured, the server will emit these headers to control cross-origin requests.

```http
Access-Control-Allow-Origin: <origin>
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, Mcp-Session-Id
Access-Control-Allow-Credentials: false
Vary: Origin
```

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

### Configure Claude Desktop with Pre-installed Executable

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

Configures Claude Desktop to use a pre-installed windows-mcp executable. This requires the full absolute path to the executable.

```json
{
  "mcpServers": {
    "windows-mcp": {
      "command": "C:\\Users\\<user>\\.local\\bin\\windows-mcp.exe",
      "args": ["serve"]
    }
  }
}
```

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

### Capture Specific Display (Snapshot Tool)

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/snapshot-screenshot-tools.md

Capture the desktop state and screenshot from a specific display monitor. Specify the display index in the `display` parameter.

```python
result = snapshot_tool(
    display=[1],
    use_vision=True
)
```

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

### Get Window Handles

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Retrieves a set of window handles (HWND) for all top-level windows currently managed by the system.

```python
desktop.get_controls_handles()
```

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

### TOML String Value Example

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/configuration.md

Demonstrates how to quote string values in TOML, especially when they contain special characters.

```toml
auth_key = "Bearer sk_..."
host = "127.0.0.1"

```

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

### Core Orchestration Module Dependencies

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/module-structure.md

Illustrates the dependencies of the main entry point (`__main__.py`) for the Windows-MCP project, including tools, desktop service, watchdog, and analytics.

```text
__main__.py (CLI & FastMCP setup)
    ├── depends on: tools/ (all tools)
    ├── depends on: Desktop (desktop service)
    ├── depends on: WatchDog
    └── depends on: PostHogAnalytics
```

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

### Get Coordinates from Label

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Use `get_coordinates_from_label` to resolve a UI element's label ID to its screen coordinates (x, y).

```python
def get_coordinates_from_label(self, label: int) -> tuple[int, int]:
    """Resolves UI element label to coordinates."""
    pass
```

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

### Get Active Window

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Retrieves the currently focused window. Optionally accepts a pre-enumerated list of windows to search within.

```python
desktop.get_active_window(windows=None)
```

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

### Launch Application with App Tool

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/system-tools.md

Launches an application using its name or path. Supports common app names like 'notepad' or 'chrome', or a full executable path.

```python
result = app_tool(mode='launch', name='notepad')
result = app_tool(mode='launch', name='chrome')
```

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

### Exclude Specific Tools in Windows-MCP

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

Starts the Windows-MCP service and disables specific tools. Use '--exclude-tools' for blocking.

```shell
windows-mcp serve --exclude-tools "PowerShell,Registry" # Disable specific tools
```

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

### Switch to Window with App Tool

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/system-tools.md

Brings a specific window to the foreground by its title. Performs a case-insensitive partial match.

```python
result = app_tool(mode='switch', name='Visual Studio Code')
```

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

### Tool Registration Pattern

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/module-structure.md

Illustrates the standard pattern for registering tools within the MCP framework. Tools are decorated with `@mcp.tool` and can utilize dependency injection for services like Desktop and Analytics. Analytics are automatically applied via a decorator.

```python
from typing import Any

from mcp import FastMCP
from mcp.analytics import with_analytics


# Assume Desktop and PostHogAnalytics are defined elsewhere
class Desktop:
    def __init__(self):
        pass

    def get_state(self):
        pass

class PostHogAnalytics:
    def __init__(self):
        pass

    async def close(self):
        pass


def register(mcp: FastMCP, *, get_desktop, get_analytics):
    @mcp.tool(name="ToolName", description="...")
    @with_analytics(get_analytics(), "Tool-Name")
    def tool_impl(arg1: Any, arg2: Any, ctx: Any = None) -> str:
        desktop = get_desktop()  # Resolve Desktop singleton
        # ... implementation
        return "result_string"
    
    # Tool automatically registered on mcp by decorator
```

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

### Get Coordinates from Multiple Labels

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Use `get_coordinates_from_labels` to resolve a list of UI element label IDs to their respective screen coordinates.

```python
def get_coordinates_from_labels(self, labels: list[int]) -> list[tuple[int, int]]:
    """Resolves multiple labels to coordinates."""
    pass
```

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

### Get Registry Value

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/data-tools.md

Retrieves a specific value from the Windows Registry. Requires the full path to the registry key and the name of the value.

```python
result = registry_tool(
    mode='get',
    path='HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Advanced',
    name='HiddenFiles'
)
```

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

### Get File Information

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/data-tools.md

Retrieves metadata for a file or directory, such as size, creation time, modification time, type, permissions, and attributes.

```python
result = file_system_tool(mode='info', path='report.xlsx')
```

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

### Capture Desktop State (Snapshot Tool)

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/snapshot-screenshot-tools.md

Use the snapshot tool to capture desktop state without a visual screenshot. This is useful for gathering system context and UI element information.

```python
result = snapshot_tool(
    use_vision=False,
    use_ui_tree=True
)
```

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

### Clone Windows-MCP Repository

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

Clone your forked repository and navigate into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/Windows-MCP.git
cd Windows-MCP
```

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

### Snapshot Tool

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/snapshot-screenshot-tools.md

Captures the complete desktop state, including system information, UI elements, and an optional screenshot with DOM extraction capabilities. It's the primary tool for understanding the current screen content and interacting with UI elements.

```APIDOC
## Snapshot Tool

### Description
Captures the complete desktop state and is the primary tool for understanding what is currently visible on screen. Returns:

- **System context**: Current language, focused window, open windows list
- **Interactive elements**: Buttons, text fields, checkboxes, dropdowns, links with screen coordinates and element IDs (labels)
- **Scrollable areas**: Regions that can be scrolled with scroll percentage
- **Visual capture**: Screenshot image (when `use_vision=True`)
- **DOM extraction**: Web page structure (when `use_dom=True` with a browser open)

The tool provides element labels (numeric IDs) that can be used with Click, Type, MultiSelect, and MultiEdit tools to interact with UI elements without requiring exact coordinates.

### Method
`_state_tool`

### Parameters
#### Optional Parameters
- **use_vision** (bool | str) - Optional - Include screenshot image in response. Set to True or "true" to capture a visual screenshot
- **use_dom** (bool | str) - Optional - Extract web page DOM instead of Windows UI tree. Only works when `use_ui_tree=True` and requires an open browser
- **use_annotation** (bool | str) - Optional - Draw colored bounding boxes around detected UI elements on the screenshot. Improves element localization
- **use_ui_tree** (bool | str) - Optional - Extract interactive and scrollable UI elements from windows. Set to False for faster capture without element tree
- **width_reference_line** (int) - Optional - Draw vertical grid lines at this interval (pixels) for spatial reasoning. Requires `use_vision=True`
- **height_reference_line** (int) - Optional - Draw horizontal grid lines at this interval (pixels) for spatial reasoning. Requires `use_vision=True`
- **display** (list[int]) - Optional - Limit capture to specific display indices (e.g., `[0]` for primary display). Omit to capture all displays
- **ctx** (Context) - Optional - MCP context (injected by framework)

### Returns
List of strings containing:
1. Desktop state summary (active window, open windows, virtual desktops)
2. UI element tree (if `use_ui_tree=True`)
3. Screenshot image as base64 (if `use_vision=True`)
4. Grid reference markers (if width/height reference lines specified)

### Examples
**Basic desktop observation:**
```python
# Capture desktop state without screenshot
result = snapshot_tool(
    use_vision=False,
    use_ui_tree=True
)
```

**Full capture with annotated screenshot:**
```python
# Capture with visual annotation
result = snapshot_tool(
    use_vision=True,
    use_annotation=True,
    use_ui_tree=True
)
```

**Browser DOM extraction:**
```python
# Extract web page DOM from open browser
result = snapshot_tool(
    use_dom=True,
    use_ui_tree=True,
    use_vision=False
)
```

**Specific display capture:**
```python
# Capture only secondary monitor
result = snapshot_tool(
    display=[1],
    use_vision=True
)
```
```

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

### Configure Claude Desktop with uvx for MSIX

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

Configures Claude Desktop to use uvx for the windows-mcp server, specifying the full absolute path to uvx.exe. This is for MSIX-packaged applications.

```json
{
  "mcpServers": {
    "windows-mcp": {
      "command": "C:\\Users\\<user>\\.local\\bin\\uvx.exe",
      "args": ["windows-mcp", "serve"]
    }
  }
}
```

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

### HTTP 403 Forbidden Error Example

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/errors-and-validation.md

This HTTP status code indicates that the client's IP address is not allowed by the IP allowlist configuration.

```http
HTTP 403 Forbidden
```

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

### HTTP 401 Unauthorized Error Examples

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/errors-and-validation.md

These HTTP status codes indicate authentication failures due to invalid, missing, or malformed bearer tokens.

```http
HTTP 401 Unauthorized
```

```http
HTTP 401 Unauthorized
```

```http
HTTP 401 Unauthorized
```

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

### DesktopState Data Structure

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/types.md

Captures a complete snapshot of the desktop, including active and all desktops, active window, list of all windows, screenshot data, cursor position, and screenshot-related metadata. It also includes UI tree state and capture time.

```python
@dataclass
class DesktopState:
    active_desktop: dict
    all_desktops: list[dict]
    active_window: Window | None
    windows: list[Window]
    screenshot: Image | None = None
    cursor_position: tuple[int, int] | None = None
    screenshot_original_size: Size | None = None
    screenshot_scale: float | None = None
    screenshot_region: BoundingBox | None = None
    screenshot_displays: list[int] | None = None
    screenshot_backend: str | None = None
    tree_state: TreeState | None = None
    capture_sec: float = 0.0
```

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

### get_state

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/desktop-service.md

Captures the complete desktop state at a moment in time, including window information, UI elements, and optionally screenshots.

```APIDOC
## get_state()

### Description
Captures the complete desktop state at a moment in time, including window information, UI elements, and optionally screenshots.

### Method
GET (conceptual)

### Parameters
#### Query Parameters
- **use_annotation** (bool | str) - Optional - Draw bounding boxes on screenshot
- **use_vision** (bool | str) - Optional - Capture screenshot image
- **use_dom** (bool | str) - Optional - Extract browser DOM (requires use_ui_tree=True)
- **use_ui_tree** (bool | str) - Optional - Extract UI element tree
- **as_bytes** (bool | str) - Optional - Return screenshot as bytes instead of PIL Image
- **scale** (float) - Optional - Scale factor for image (0.1-1.0)
- **grid_lines** (tuple[int, int] | None) - Optional - Tuple of (width_interval, height_interval) for grid overlay
- **display_indices** (list[int] | None) - Optional - List of display indices to capture
- **max_image_size** (Size | None) - Optional - Size limit for image (will be scaled if exceeded)

### Returns
`DesktopState` object containing windows, UI elements, and optional screenshot

### Raises
`ValueError` if use_dom=True and use_ui_tree=False
```

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

### Boolean Coercion Example

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/errors-and-validation.md

Illustrates how string values 'false' and 'true' (case-insensitive) are coerced to boolean False and True, respectively. Other strings may raise ValueError.

```string
False or "false" (case-insensitive) → False
```

```string
True or "true" (case-insensitive) → True
```

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

### Tools Module Dependencies

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/module-structure.md

Summarizes the dependencies for all tool implementations within the `tools/` directory, highlighting their reliance on core services and infrastructure.

```text
tools/ (all tool implementations)
    ├── depends on: Desktop (for all operations)
    ├── depends on: filesystem/, powershell/, process/, registry/, notifications/
    └── depends on: infrastructure/ (auth, security, analytics)
```

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

### Format Code with Ruff

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

Command to format all code in the current directory according to project style guidelines using Ruff.

```bash
ruff format .

```

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

### Get Raw Webpage Content

Source: https://github.com/cursortouch/windows-mcp/blob/main/_autodocs/data-tools.md

Use scrape_tool with `use_sampling=False` to retrieve the raw content of a webpage without any processing or sampling. This is useful when you need the exact HTML source.

```python
result = await scrape_tool(
    url='https://example.com',
    use_sampling=False
)
```