Win32

You can deploy this MCP server on Windows to automate and control Windows applications through the Model Context Protocol. It enables intelligent text interactions, structured OCR, screen capture, mouse and keyboard input, window and process management, and batch tool sequences, all accessible to MCP-compatible agents.

How to use

Begin by ensuring you have a running MCP client that can communicate over STDIO with the server. The server exposes a rich set of tools you can invoke from your client to perform desktop automation tasks. You will typically send high-level commands like find text on screen, click a button by its label, capture screenshots, read and write the clipboard, or manage windows and processes. Use multi-step sequences to batch several actions in a single request, reducing round-trips.

How to install

Prerequisites: install Python 3.10 or newer. Install Tesseract OCR if you plan to use OCR features.

Install from GitHub (recommended for the latest v2.0):

pip install git+https://github.com/RandyNorthrup/win32-mcp-server.git

Install from PyPI (stable release):

pip install win32-mcp-server

Install from source (editable):

git clone https://github.com/RandyNorthrup/win32-mcp-server.git
cd win32-mcp-server
pip install -e .

Configuration

Configure clients to connect to the server using a standard STDIO transport. You can add the server configuration to your editor or client settings as shown in the examples.

{
  "servers": {
    "win32_inspector": {
      "type": "stdio",
      "command": "win32-mcp-server",
      "args": []
    }
  }
}

Security considerations

This server has powerful system control capabilities. Use it only in trusted environments where you control the MCP client. Follow best practices to minimize exposure, review tool usage logs, and restrict access to trusted users.

Troubleshooting

If you encounter issues, check common problems and solutions listed here.

• TesseractNotFoundError: Install Tesseract from the official project and ensure it is on PATH
• PermissionError: Access is denied: Run your editor and MCP client with appropriate privileges
• ModuleNotFoundError: No module named 'mcp': Install the package in editable mode or via PyPI
• Window not found: [title]: Use partial titles and rely on fuzzy matching
• OCR returns garbled text: Adjust preprocessing to dark_bg or high_contrast
• HiDPI coordinate issues: Run health_check to verify DPI settings

Dependencies

The server relies on the following libraries and tools to operate.

• mcp — Model Context Protocol SDK
• mss — Screen capture
• Pillow — Image processing
• NumPy — Image preprocessing for OCR
• PyAutoGUI — Mouse and keyboard automation
• PyGetWindow — Window control
• pyperclip — Clipboard operations
• pytesseract — OCR wrapper
• psutil — Process management
• RapidFuzz — Fuzzy string matching

Notes

The recommended workflow is to install the server, then configure your MCP client to connect via STDIO, and finally begin issuing automated commands to interact with Windows applications across your environment.

All 47 Tools overview

The server provides a comprehensive set of tools organized into categories for desktop automation, screen capture, OCR, input, window and process management, and system health. Here is the tool family overview with purpose descriptions.

• Smart Automation: click_text finds text on screen and clicks it; find_text_on_screen locates text with coordinates; wait_for_text polls for text; assert_text_visible verifies text visibility; fill_field types into labeled fields; get_window_snapshot combines screenshot with OCR data; right_click_menu reads menu items from a context menu; execute_sequence runs multiple tools in order without extra round-trips

MSP Tools — quick reference list

The following individual tools are available for practical automation tasks. Each entry includes a short description of its capability.

• capture_screen: Full screen screenshot in PNG/JPEG/WebP formats
• capture_window: Screenshot of a specific window identified by fuzzy title
• capture_monitor: Capture a selected monitor by index
• list_monitors: Describe monitors with resolution and DPI
• get_pixel_color: Read the color at a screen coordinate
• compare_screenshots: Pixel-level image comparison with similarity score
• ocr_screen: Extract text from the full screen
• ocr_region: Extract text from a defined region
• ocr_window: Extract text from a specific window
• ocr_screen_structured: Structured OCR with bounding boxes for the entire screen
• ocr_region_structured: Region OCR with bounding boxes
• click: Click at coordinates with specified mouse button and count
• double_click: Double-click at coordinates
• triple_click: Triple-click at coordinates
• drag: Drag from start to end with duration
• mouse_position: Report current cursor position
• mouse_move: Move cursor with smooth animation
• scroll: Vertical scrolling at a position
• scroll_horizontal: Horizontal scrolling at a position
• type_text: Type text with Unicode support
• press_key: Press a single key or a combination
• hotkey: Execute a hotkey combination from an array
• clipboard_copy: Copy text to clipboard
• clipboard_paste: Read clipboard contents
• list_windows: List open windows with optional title filter
• get_window_info: Retrieve window details like PID and memory
• focus_window: Bring a window to foreground
• close_window: Close a window by title
• minimize_window: Minimize a window
• maximize_window: Maximize a window
• restore_window: Restore a window from minimized/maximized state
• resize_window: Resize a window to exact dimensions
• move_window: Move a window to exact coordinates
• wait_for_window: Wait for a window to appear by title
• list_processes: List processes with filtering/sorting/pagination
• kill_process: Terminate a process with graceful and force options
• start_process: Launch an application with optional wait for completion
• wait_for_idle: Wait for a process CPU usage to drop below threshold
• health_check: Verify dependencies and system status

End of tool overview

This section provides a complete reference for all tool types available in the server, covering smart automation, screen capture, OCR, input, window management, process control, and system health checks.

Available tools

click_text

Find text on screen and click it, with no coordinates required.

find_text_on_screen

Locate all occurrences of text on the screen and return their coordinates.

wait_for_text

Poll for text to appear on screen with an optional timeout.

assert_text_visible

Check whether specific text is visible on screen.

fill_field

Click a labeled input field and type a value.

get_window_snapshot

Take a screenshot and return it with OCR data.

right_click_menu

Right-click and OCR the items in the context menu.

execute_sequence

Run up to 50 tools in a predefined sequence with a single request.

capture_screen

Capture the entire screen in PNG/JPEG/WebP formats.

capture_window

Capture a specific window identified by title similarity.

capture_monitor

Capture an image from a specified monitor by index.

list_monitors

List monitor information including resolutions and DPI.

get_pixel_color

Read RGB/hex color values from a screen coordinate.

compare_screenshots

Compare two images at the pixel level with a similarity score.

ocr_screen

Extract text from the full screen.

ocr_region

Extract text from a defined region.

ocr_window

Extract text from a specific window.

ocr_screen_structured

Structured OCR for the full screen with bounding boxes.

ocr_region_structured

Structured OCR for a region with bounding boxes.

click

Click at coordinates with chosen mouse button and click count.

double_click

Perform a double-click at coordinates.

triple_click

Perform a triple-click at coordinates.

drag

Drag from start to end with a specified duration.

mouse_position

Return the current cursor position.

mouse_move

Move the cursor with smooth animation.

scroll

Vertical scroll at a position.

scroll_horizontal

Horizontal scroll at a position.

type_text

Type text with Unicode support or fallback to clipboard paste.

press_key

Press a single key or a combination of keys.

hotkey

Execute a hotkey sequence from a key array.

clipboard_copy

Copy text to the system clipboard.

clipboard_paste

Read text from the clipboard.

list_windows

List open windows with optional title filtering.

get_window_info

Provide detailed window information such as PID and memory usage.

focus_window

Set a window as the foreground window.

close_window

Close a window by its title.

minimize_window

Minimize a window.

maximize_window

Maximize a window.

restore_window

Restore a window from minimized or maximized state.

resize_window

Resize a window to exact width and height.

move_window

Move a window to an exact x, y position.

wait_for_window

Wait for a window to appear by title with a timeout.

list_processes

List processes with optional filtering, sorting, and pagination.

kill_process

Terminate a process with graceful shutdown and a force fallback.

start_process

Launch an application with optional wait until it completes.

wait_for_idle

Wait for a process CPU usage to drop below a threshold.

health_check

Provide a full dependency and system health report.