Skip to main content
Glama
windows2-mcp

windows2-mcp

by verisoft-ai

windows2-mcp

MCP服务器,将Windows桌面UI自动化作为工具暴露给AI代理,基于appium-desktop-driver构建。

此前作为desktop-driver-mcp包含在appium-desktop-driver中;现已拆分为独立包,以便MCP服务器和Appium驱动程序可以独立安装、版本管理和发布。

前提条件

  • 运行中的Appium服务器,已安装appium-desktop-driver:

npm install -g appium
appium driver install --source=npm appium-desktop-driver
appium --port 4723

Related MCP server: windows-computer-use-mcp

安装

npm install -g windows2-mcp

或直接使用npx windows2-mcp运行。

配置

环境变量(启动时读取):

变量

默认值

描述

APPIUM_HOST

127.0.0.1

运行中的Appium服务器主机

APPIUM_PORT

4723

运行中的Appium服务器端口

MCP客户端配置

{
  "mcpServers": {
    "windows2-mcp": {
      "command": "npx",
      "args": ["-y", "windows2-mcp"],
      "env": {
        "APPIUM_HOST": "127.0.0.1",
        "APPIUM_PORT": "4723"
      }
    }
  }
}

工具

请参阅docs/TOOLS.md获取完整的工具参考(约85个工具,涵盖会话管理、元素发现、交互、UIA模式、窗口管理、视觉等),由当前工具源生成。

开发

npm install
npm run build
npm run test
npm run lint

许可证

Apache-2.0

Available Tools

90 tools
add_to_selectionA

Add an item to the current selection in a multi-select container via the UIA SelectionItem pattern (does not deselect existing items).

Inputs: elementId (required).

advanced_clickA

Perform a click at an element or absolute screen coordinates, with optional modifier keys, multiple clicks, or custom duration. Use for right-click, double-click, Ctrl+click, or coordinate-based clicks. Simulates a real mouse event at screen coordinates, so the target window must be visible and in the foreground.

Inputs: x, y, times, button, +4 more.

analyze_screenA
Read-only

Take a screenshot and return it to the calling agent for visual analysis. No external API key required. Includes a DPI-aware coordinate mapping so any coordinates identified are ready for click interactions.

Inputs: prompt (required).

attach_dotnet_bridgeA

Inject the .NET bridge into the CLR process owning the current session window. Use this after creating a session (with appTopLevelWindow) when dotnetBridge was NOT set at session creation time. Needed for WinForms/WPF apps built with custom-drawn control libraries (e.g. DevExpress) whose controls expose little or nothing via plain UIA. Only works on an already-running process — there is no launch-time injection path. Both .NET Framework (clr.dll) and CoreCLR (.NET 5+, coreclr.dll) targets are supported automatically.

Inputs: no named parameters.

attach_java_swingA

Inject the Java accessibility agent into the JVM owning the current session window. Use this after creating a session (with app or appTopLevelWindow) when javaSwing was NOT set at session creation time. Once called, element finding will use Java class names and accessible names instead of UIA.

Inputs: jdkPath.

attach_sessionA

Attach to an existing Appium session by session ID. Ask the user to provide the session ID — it is visible in Appium Inspector or in the Appium server logs next to the session creation event.

Inputs: sessionId (required).

clear_elementB

Clear the text content of an input element.

Inputs: elementId (required).

click_and_dragC

Click and drag from one position to another. Useful for resizing, reordering, or moving elements.

Inputs: endX, endY, button, startX, +5 more.

click_elementA

Click a UI element by its element ID. Targets the element directly — does not require the window to be focused or in the foreground.

Inputs: elementId (required).

close_appA
Destructive

Close the application under test without ending the Appium session. Only call when explicitly asked.

Inputs: no named parameters.

close_windowA
Destructive

Close a window element via the UIA Window pattern.

Inputs: elementId (required).

collapse_elementB
Idempotent

Collapse an expanded element via the UIA ExpandCollapse pattern.

Inputs: elementId (required).

create_sessionA
Destructive

Launch a Windows application and start a new Appium session. Ask the user before calling — confirm they want a new app instance launched.

Inputs: app, jdkPath, javaSwing, appArguments, +13 more.

delete_fileA
Destructive

Delete a file on the machine running the driver. Requires the "modify_fs" insecure feature to be enabled on the Appium server.

Inputs: path (required).

delete_folderA
Destructive

Delete a folder (recursively by default) on the machine running the driver. Requires the "modify_fs" insecure feature to be enabled on the Appium server.

Inputs: path (required), recursive.

delete_sessionA
Destructive

End the current Appium session and close the app. Only call this when the user explicitly asks to stop or end the session. Never call autonomously — always confirm with the user before terminating.

Inputs: no named parameters.

execute_extension_commandA
Destructive

Run any extension command (execute method) of the driver or an active plugin by name, e.g. "windows: getWindows" or "pcomm: getScreenText". Call list_extension_commands first to get the exact name and parameters. Prefer a dedicated tool when one exists — use this for commands without one, including commands added by plugins. Pass element IDs (from find_element) as plain strings, usually under elementId. Element references in the result are returned as plain element ID strings. Some commands are destructive (closing apps, deleting files): confirm with the user before running those.

Inputs: command (required), args.

execute_powershellA
Destructive

Run a raw PowerShell script or command on the machine running the driver, inside the session's persistent PowerShell process. Use for arbitrary automation not covered by another tool (registry edits, service control, file inspection, etc). Runs with the same privileges as the driver process — treat as unrestricted code execution.

Inputs: script (required).

expand_elementA
Idempotent

Expand a collapsible element (tree node, combo box, menu) via the UIA ExpandCollapse pattern.

Inputs: elementId (required).

find_by_visionA
Read-only

Take a screenshot and delegate visual analysis to an external vision model, returning the result. Use when visual analysis should be performed by a separate model rather than by the calling agent. Requires an external API key: ANTHROPIC_API_KEY (claude-), OPENAI_API_KEY (gpt-/o-series), GEMINI_API_KEY (gemini-), or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (amazon.nova-).

Inputs: model (required), prompt (required), responseFormat, includeAnnotatedImage.

find_child_elementA
Read-only

Find a child element scoped to a known parent element's subtree. Use when the same selector exists in multiple parts of the UI and you need to narrow the search. Preferred strategy order for reliable automation: 1) "accessibility id" (AutomationId) — most stable, use whenever available 2) "name" — good for static labels not subject to localization 3) "xpath" — flexible fallback, e.g. //Button[@Name="OK"] 4) other strategies — use only when the above are unavailable. After interacting with an element you plan to use in generated test code, call get_element_info to capture the best locator.

Inputs: selector (required), strategy (required), parentElementId (required).

find_elementA
Read-only

Find a single UI element in the current app window. Returns an element ID string. Returns an error if not found. Preferred strategy order for reliable automation: 1) "accessibility id" (AutomationId) — most stable, use whenever available 2) "name" — good for static labels not subject to localization 3) "xpath" — flexible fallback, e.g. //Button[@Name="OK"] 4) other strategies — use only when the above are unavailable. After interacting with an element you plan to use in generated test code, call get_element_info to capture the best locator.

Inputs: selector (required), strategy (required).

find_elementsA
Read-only

Find all UI elements matching the selector. Returns a JSON array of element ID strings. Preferred strategy order for reliable automation: 1) "accessibility id" (AutomationId) — most stable, use whenever available 2) "name" — good for static labels not subject to localization 3) "xpath" — flexible fallback, e.g. //Button[@Name="OK"] 4) other strategies — use only when the above are unavailable. After interacting with an element you plan to use in generated test code, call get_element_info to capture the best locator.

Inputs: selector (required), strategy (required).

focus_elementA
Idempotent

Set focus to an element via the UIA Focus pattern (windows: setFocus). Required before keyboard-driven interactions such as send_keys on a specific control.

Inputs: elementId (required).

get_active_elementA
Read-only

Get the element ID of the element that currently has keyboard focus.

Inputs: no named parameters.

get_all_selected_itemsA
Read-only

Get all currently selected items in a multi-select container via the UIA Selection pattern. Returns a JSON array of element IDs.

Inputs: elementId (required).

get_attributeA
Read-only

Get an attribute or property of a UI element. Common attributes: Name, AutomationId, ClassName, IsEnabled, IsOffscreen, ControlType, Value.Value. Returns an empty string when the attribute is absent.

Inputs: attribute (required), elementId (required).

get_clipboardA
Read-only

Read the current clipboard contents as a base64-encoded string.

Inputs: contentType.

get_contextsA
Read-only

List all available contexts. Returns "NATIVE_APP" for the UIA element tree, and any embedded webview contexts as "WEBVIEW_".

Inputs: no named parameters.

get_current_contextA
Read-only

Get the current active context. Returns "NATIVE_APP" (UIA element tree, find_element works here) or "WEBVIEW_" (web DOM, standard web selectors apply). Call this if unsure which context is active before interacting.

Inputs: no named parameters.

get_current_window_handleA
Read-only

Get the handle of the current window (as a hex HWND string, e.g. "0x00abc123").

Inputs: no named parameters.

get_device_timeA
Read-only

Get the current date/time on the Windows device.

Inputs: no named parameters.

get_element_infoA
Read-only

Retrieve all key UIA properties of an element and get ranked selector suggestions for test automation. Returns: Name, AutomationId, ClassName, ControlType, IsEnabled, and a prioritized list of selectors. ALWAYS call this after find_element when generating automated test code — it gives you the best locator to use. Selector reliability order: accessibility id (AutomationId) = highest → name → xpath → class name = lowest. For .NET/C# Appium: use MobileBy.AccessibilityId(automationId) when AutomationId is non-empty.

Inputs: elementId (required).

get_element_rectB
Read-only

Get the position (relative to the app window) and size of an element.

Inputs: elementId (required).

get_element_screenshotA
Read-only

Take a screenshot cropped to a single element, returned as base64 PNG. Not supported in IE context.

Inputs: elementId (required).

get_element_tag_nameA
Read-only

Get an element's tag name (its UIA ControlType in native context, or HTML tag name in IE/webview context).

Inputs: elementId (required).

get_element_valueB
Read-only

Get the value of an element via the UIA Value pattern.

Inputs: elementId (required).

get_monitorsA
Read-only

List all connected monitors with their bounds, working area, device name, and whether each is the primary display.

Inputs: no named parameters.

get_native_childrenA
Read-only

Fallback for legacy WinForms/ActiveX controls that expose zero UIA children (verify with get_page_source / Inspect.exe first). Bypasses UI Automation and walks the control's raw IAccessible (MSAA) tree instead — many of these controls were built with hand-written MSAA support for screen readers, exposing rows/cells as "simple children" (plain integer childIds with no HWND) that UIA and Win32 child-window enumeration can never see. Returns a tree of {name, role, value, description, state, defaultAction, rect, childCount, children}. If supported is false, or the root node has zero children, the control paints its own content with no accessibility tree either, and there is no structural data left to recover — use find_by_vision / analyze_screen plus advanced_click instead.

Inputs: elementId (required).

get_orientationA
Read-only

Get the current display orientation ("LANDSCAPE" or "PORTRAIT").

Inputs: no named parameters.

get_page_sourceA
Read-only

Get the XML representation of the current UIA element tree. Use as the source of truth for current UI state — call whenever you are unsure what is on screen or after a UI change (navigation, dialog, window switch). Inspect the result to discover element Names and AutomationIds.

Inputs: no named parameters.

get_selected_itemA
Read-only

Get the first selected item in a container (e.g. ListBox, TreeView) via the UIA Selection pattern. Returns an element ID.

Inputs: elementId (required).

get_session_statusA
Read-only

Check whether a session is currently active in this MCP server instance.

Inputs: no named parameters.

get_textA
Read-only

Get the visible text content of a UI element.

Inputs: elementId (required).

get_urlA
Read-only

Get the current page URL. Only supported when the active window is an IE window (IE mode is enabled automatically by switch_to_window / switch_to_window_by_title when the target is an Internet Explorer window).

Inputs: no named parameters.

get_window_elementA
Read-only

Get the element ID of the current session's root window element.

Inputs: no named parameters.

get_window_handlesA
Read-only

Get all available window handles for the current session. Use when the app has multiple windows.

Inputs: no named parameters.

get_window_rectA
Read-only

Get the position and size of the current app window.

Inputs: no named parameters.

get_windowsA
Read-only

Get all visible windows including untitled ones. Returns an array of { handle, title, className } objects. Use handle to switch to any window (including those with no title) via switch_to_window. Use className to identify untitled windows such as popups and dialogs.

Inputs: no named parameters.

get_window_titleA
Read-only

Get the title (Name property of the root window element) of the current window.

Inputs: no named parameters.

hoverA

Move the mouse pointer from one position to another, optionally with modifier keys held. Useful for hover effects and drag-without-click.

Inputs: endX, endY, startX, startY, +4 more.

invoke_elementA

Invoke the default action of an element via the UIA Invoke pattern without simulating mouse input. Use for elements that do not respond to mouse clicks.

Inputs: elementId (required).

is_element_displayedA
Read-only

Check whether a UI element is visible on screen (not off-screen).

Inputs: elementId (required).

is_element_enabledA
Read-only

Check whether a UI element is enabled and interactable.

Inputs: elementId (required).

is_element_selectedA
Read-only

Check whether a checkbox, radio button, or toggle is checked/selected. Works for both UIA and Java Swing elements. Returns "true" or "false". Note: tri-state (indeterminate) checkboxes return "false" — indeterminate cannot be distinguished from unchecked via this tool.

Inputs: elementId (required).

is_multi_selectA
Read-only

Check whether a container (e.g. ListBox) allows multiple items to be selected via the UIA Selection pattern.

Inputs: elementId (required).

launch_appA

Launch the application configured for this session (re-launch if it was closed).

Inputs: no named parameters.

list_extension_commandsA
Read-only

List the extension commands (execute methods) available in the current session that have no dedicated tool, as Appium's listExtensions reports them: the driver's own "windows: …" commands plus the commands of each active Appium plugin (e.g. .NET / Java / SAP bridges, PCOMM). Commands already covered by a dedicated tool are left out — use that tool instead. Each line shows the command name, its parameters (? = optional) and its description. Run a listed command with execute_extension_command.

Inputs: filter.

maximize_current_windowA
Idempotent

Maximize the current session's root window (whole-window operation — does not require an elementId, unlike maximize_window).

Inputs: no named parameters.

maximize_windowB
Idempotent

Maximize a window element via the UIA Window pattern.

Inputs: elementId (required).

minimize_current_windowA
Idempotent

Minimize the current session's root window (whole-window operation — does not require an elementId, unlike minimize_window).

Inputs: no named parameters.

minimize_windowB
Idempotent

Minimize a window element via the UIA Window pattern.

Inputs: elementId (required).

perform_actionsA

Perform a raw W3C WebDriver Actions sequence (pointer/key/wheel input sources). Lower-level than advanced_click/hover/scroll/send_keys — use only when you need multi-source synchronized input (e.g. a key held down during a pointer drag) that those higher-level tools cannot express.

Inputs: actions (required).

pull_fileA
Read-only

Read a file from the filesystem of the machine running the driver, returned as base64. Requires the "modify_fs" insecure feature to be enabled on the Appium server.

Inputs: remotePath (required).

push_fileA
Destructive

Write a file to the filesystem of the machine running the driver. Requires the "modify_fs" insecure feature to be enabled on the Appium server.

Inputs: base64Data (required), remotePath (required).

release_actionsA
Idempotent

Release all keys and pointer buttons currently held down by a prior perform_actions call. Call this to reset input state if a perform_actions sequence left keys/buttons stuck down (e.g. after an error mid-sequence).

Inputs: no named parameters.

remove_from_selectionB

Remove an item from the current selection in a multi-select container via the UIA SelectionItem pattern.

Inputs: elementId (required).

restore_windowA
Idempotent

Restore a minimized or maximized window to its normal state via the UIA Window pattern.

Inputs: elementId (required).

scrollB

Scroll the mouse wheel at an element or screen coordinate.

Inputs: x, y, deltaX, deltaY, +2 more.

scroll_element_into_viewA
Idempotent

Scroll a container so the given element becomes visible, via the UIA ScrollItem pattern. Use before clicking an element that may be outside the visible scroll area.

Inputs: elementId (required).

select_from_comboboxA

Select an entry by its text from a combo box / dropdown (or any list box or tree) in one call (windows: selectFromCombobox). Opens the container if needed, finds the entry whose Name is exactly value (including entries of virtualized lists that are not yet in the tree), selects it, and closes the popup again. Prefer this over expand_element + find_element + select_item/click_element whenever you know the text of the entry to pick. Pass the combo box itself, not an item inside it. Matching is exact and case-sensitive; if no entry matches, the popup is closed and the tool fails with "no such element" — then call expand_element and get_page_source to read the available entry names. Not suitable when the dropdown opens as a separate top-level window, or for editable combo boxes where you want to type free text (use set_element_value).

Inputs: value (required), elementId (required).

select_itemA

Select an item in a list box, tab control, or combo box via the UIA SelectionItem pattern (windows: select). Use when click does not trigger selection.

Inputs: elementId (required).

send_keysA

Send keyboard input. Each action can be a pause (ms delay), text to type, or a virtual key code press/release. Simulates real OS-level key events sent to whatever window currently has keyboard focus — the target window must be focused, and this cannot target a specific element. Use for key combos (Ctrl+C, Alt+Tab), navigation keys, or typing into controls that have no addressable element.

Inputs: actions (required), forceUnicode.

set_clipboardB

Set the clipboard contents from a base64-encoded string.

Inputs: b64Content (required), contentType.

set_contextA

Switch the active context. Pass "NATIVE_APP" to return to the UIA element tree, or a "WEBVIEW_" from get_contexts to switch into an embedded webview.

Inputs: name (required).

set_element_valueA

Set the value of an element via the UIA Value or RangeValue pattern (e.g. sliders, spin boxes).

Inputs: value (required), elementId (required).

set_urlA

Navigate the current IE window to a URL. No keyboard shortcuts (Ctrl+L) needed and the window does not need to be in the foreground — this calls IHTMLWindow2.navigate directly through the IE COM bridge. Only supported when the active window is an IE window.

Inputs: url (required).

set_valueA

Set the text value of an input element (clears first then types). Sets the value directly on the element — does not require the window to be focused or in the foreground.

Inputs: value (required), elementId (required).

set_window_rectA

Move and/or resize the current session's root window. Restores the window to normal state first (move/resize fail while maximized or minimized). Pass null for any of x/y/width/height to leave that dimension unchanged.

Inputs: x (required), y (required), width (required), height (required).

start_recording_screenA

Start an FFmpeg-based screen recording. If a recording is already running it is stopped and restarted by default. Call stop_recording_screen to end it and retrieve the video.

Inputs: preset, videoFps, timeLimit, audioInput, +5 more.

stop_recording_screenB
Read-only

Stop the current screen recording and return the video. Returns the video as base64 by default, or uploads it to a remote destination first if remotePath is provided.

Inputs: pass, user, method, headers, +3 more.

switch_to_default_contentA

Switch back to the top-level document after a switch_to_frame call. Required before interacting with elements outside the frame. Only supported in IE context.

Inputs: no named parameters.

switch_to_frameA

Switch context into an iframe or frame inside an IE window. After switching, element finds are scoped to that frame's document. Provide exactly one of: index (0-based integer), name (frame name/id attribute), or elementId (element ID of the iframe element). Only supported in IE context (after switch_to_window targeting an IE window).

Inputs: name, index, elementId.

switch_to_parent_frameA

Switch context to the parent frame of the current frame. Only supported in IE context; behaves the same as switch_to_default_content there.

Inputs: no named parameters.

switch_to_windowA

Switch focus to a different window by its handle (from get_window_handles).

Inputs: handle (required).

switch_to_window_by_titleA

Switch focus to a window by its title. By default uses case-insensitive substring matching so partial titles work (e.g. "Notepad" matches "Untitled - Notepad"). Set exact=true to require a full case-insensitive match.

Inputs: title (required), exact.

toggle_elementA

Toggle a checkbox or toggle button via the UIA Toggle pattern. To confirm the resulting state, call is_element_selected after this.

Inputs: elementId (required).

wait_for_elementA
Read-only

Wait for a UI element to appear within a configurable timeout, then return its element ID. Useful after dialog opens, page transitions, or loading spinners disappear. Preferred strategy order for reliable automation: 1) "accessibility id" (AutomationId) — most stable, use whenever available 2) "name" — good for static labels not subject to localization 3) "xpath" — flexible fallback, e.g. //Button[@Name="OK"] 4) other strategies — use only when the above are unavailable. After interacting with an element you plan to use in generated test code, call get_element_info to capture the best locator.

Inputs: selector (required), strategy (required), timeoutMs, pollIntervalMs.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 90 tools

    Disambiguation4/5

    The descriptions are unusually careful about distinguishing near-neighbors: maximize_current_window vs maximize_window, get_windows vs get_window_handles, click_element vs advanced_click vs invoke_element, and set_value vs set_element_value all carry explicit guidance. A few pairs (get_windows/get_window_handles, get_attribute/get_element_info/get_element_value/get_text) still overlap enough that misselection is plausible, but the docs largely resolve them.

    Naming Consistency4/5

    The vast majority follow a clean snake_case verb_noun pattern (find_element, switch_to_window, set_clipboard, start_recording_screen) with a consistent is_* prefix for predicates. Minor deviations exist—bare verbs (hover, scroll) and adjective-prefixed names (advanced_click, find_by_vision)—but overall the convention is predictable.

    Tool Count2/5

    90 tools is far too many to present as a coherent set, well past the 25+ threshold where selection burden becomes real. The domain (full Appium Windows driver surface) is broad and the extension-command fallback shows curation effort, but the count is still excessive for practical agent use.

    Completeness5/5

    Coverage is essentially exhaustive for Windows UI automation: session lifecycle, element discovery and interaction, UIA pattern operations, window/frame/webview context switching, input simulation, file and clipboard I/O, screen recording, vision fallbacks, and raw PowerShell escape hatch. No obvious dead ends for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for AI agents to automate Windows WPF apps with semantic UI Automation selectors, screenshots, recording, and FlaUI test generation.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives AI agents human-like control over Windows via visual perception and simulated mouse and keyboard input, enabling automation of any application without APIs.
      33 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI clients to automate Windows desktop applications through window manipulation, image recognition, OCR, keyboard/mouse simulation, and memory operations via the MCP protocol.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for driving any Windows app through five layers including OCR, UI Automation, and direct OS operations. Enables AI agents to control Windows desktop and OS cursor-free, even on background/locked windows.
      122 npm
      3
      MIT