oswright (Ask 812)

OSWright

一种模型上下文协议（MCP）服务器，提供 操作系统级桌面自动化 使用OCR和图像匹配。此服务器使LLM能够与任何桌面应用程序交互——单击按钮、键入文本、阅读屏幕和填写表单——就像 剧作家MCP 适用于浏览器。

主要特点

• 跨平台。 Windows（Win32 API）、Linux（pynput/X11）、macOS（pynput/Quartz）。
• 可访问性树。 通过Windows UI自动化按角色和名称确定地查找元素——100%准确、即时，不需要模型。
• 快速OCR。 Windows OCR（内置，即时），支持Linux/macOS的EasyOCR回退。结果会自动缓存。
• 图像匹配。 通过OpenCV按模板图像定位元素。
• 窗口管理。 列出、聚焦、最小化、关闭和截图特定窗口。
• 屏幕截图差异。 检测屏幕何时发生变化 wait_for_change.
• 剪贴板访问。 读写系统剪贴板以进行数据传输。
• 应用程序启动器。 启动应用程序并等待其加载。
• 自动快照。 每个操作都会返回一个屏幕截图，因此代理始终可以看到当前状态。
• 35+MCP工具。 屏幕、OCR、UIA、鼠标、键盘、窗口、剪贴板和复合操作。
• 测试套件。 22项涵盖核心功能的自动化测试。

需求

• Python 3.10或更新版本
• VS Code、Cursor、Windsurf、Claude Desktop或任何其他MCP客户端

入门

首先，在客户端安装OSWright MCP服务器。

标准配置 适用于大多数工具：

{
  "mcpServers": {
    "oswright": {
      "command": "uvx",
      "args": ["oswright"]
    }
  }
}

注： 如果你没有 uvx，您可以使用 pip install oswright 然后设置 "command": "oswright" 直接。

Claude Desktop

遵循MCP安装 指南，使用上面的标准配置。

Claude Code

claude mcp add oswright uvx oswright

VS Code

添加到您的用户或工作区 settings.json 在...之下 mcp.servers:

{
  "mcp": {
    "servers": {
      "oswright": {
        "command": "uvx",
        "args": ["oswright"]
      }
    }
  }
}

或者使用VS Code CLI：

code --add-mcp '{"name":"oswright","command":"uvx","args":["oswright"]}'

Cursor

首选 Cursor Settings -> MCP -> Add new MCP Server.命名它 oswright，使用 command 使用命令键入 uvx oswright.

Windsurf

关注Windsurf MCP 文档.使用上面的标准配置。

Cline

添加到您的 cline_mcp_settings.json:

{
  "mcpServers": {
    "oswright": {
      "type": "stdio",
      "command": "uvx",
      "args": ["oswright"],
      "disabled": false
    }
  }
}

Goose

首选 Advanced settings -> Extensions -> Add custom extension.命名它 oswright，使用类型 STDIO，并设置 command 到 uvx oswright.

Using pip instead of uvx

如果您更喜欢标准pip安装：

pip install oswright

然后使用此配置：

{
  "mcpServers": {
    "oswright": {
      "command": "oswright"
    }
  }
}

或者直接运行：

python -m oswright

配置

OSWright MCP服务器支持以下参数。它们可以在JSON配置中作为 "args" 列表：

示例：多语言OCR

{
  "mcpServers": {
    "oswright": {
      "command": "uvx",
      "args": ["oswright", "--ocr-languages", "en", "es", "fr"]
    }
  }
}

独立MCP服务器（SSE）

从远程计算机或工作进程运行时，使用SSE传输：

uvx oswright --port 8931

然后在MCP客户端配置中：

{
  "mcpServers": {
    "oswright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

平台说明

工具

Screen

• 截图 --对屏幕或某个区域进行截图。将图像作为原生MCP图像内容返回。（可选）保存到文件路径。

- 只读： 真

• get_screen_info --获取屏幕尺寸和显示器数量。

- 只读： 真

OCR / Text Finding

• find_text_on_screen --使用OCR查找屏幕上出现的所有文本。返回具有坐标和置信度的匹配项。

- 参数： text, exact、区域边界， monitor - 只读： 真

• read_screen_text --使用OCR读取屏幕上的所有可见文本。返回每个检测到的具有位置的文本元素。

- 参数：区域边界， monitor - 只读： 真

Image Matching

• find_image_on_screen --使用OpenCV模板匹配在屏幕上查找模板图像的所有出现。

- 参数： template_path, threshold, monitor - 只读： 真

Mouse

• 鼠标点击 --在坐标或当前位置单击鼠标。返回屏幕截图。

- 参数： x, y, button, clicks

• 鼠标双击 --双击坐标或当前位置。返回屏幕截图。

• mouse_move --将鼠标光标移动到屏幕坐标。

• 鼠标_滚动 --滚动鼠标滚轮。返回屏幕截图。

- 参数： amount, x, y

• 鼠标拖动 --从一个点拖动到另一个点。返回屏幕截图。

- 参数： start_x, start_y, end_x, end_y, button, duration

• get_mouse_position --获取当前鼠标光标位置。

- 只读： 真

Keyboard

• 类型文本 --逐个字符键入文本。返回屏幕截图。

- 参数： text, delay

• 按键 --按下按键或组合键，如 Enter, Ctrl+C, Alt+Tab。返回屏幕截图。

- 参数： key

Compound Actions

• 点击_文本 --通过OCR查找文本并单击它。自动重试，直到找到或超时。返回屏幕截图。

- 参数： text, exact, button, timeout, poll_interval, monitor

• double_click_text --通过OCR查找文本并双击。返回屏幕截图。

• right_click_text --通过OCR查找文本并右键单击。返回屏幕截图。

• hover_text --通过OCR查找文本并将鼠标悬停在其上。返回屏幕截图。

• 填充字段 --找到一个标签，单击它，清除并键入一个值。返回屏幕截图。

- 参数： target_text, value, exact, timeout, monitor

• fill_form --在一次通话中填写多个字段。减少往返次数。

- 参数： fields （列表 {label, value}), timeout, monitor

• 等待文本 --等待文本出现在屏幕上。通过OCR进行民意调查。

- 参数： text, exact, timeout, poll_interval, monitor - 只读： 真

• wait_for_text_gone --等待文本从屏幕上消失。

- 参数： text, exact, timeout, poll_interval, monitor - 只读： 真

• 等待时间 --等待指定的时间（上限为30秒），然后截图。

Window Management

• list_windows --列出所有可见的窗口。可选择按标题子字符串过滤。

- 参数： title_filter - 只读： 真

• focus_window --按标题将窗口置于前台。返回屏幕截图。

- 参数： title

• 关闭窗口 --按标题关闭窗口（发送WM_Close）。返回屏幕截图。

- 参数： title

• 最小化窗口 --按标题最小化窗口。返回屏幕截图。

- 参数： title

• 屏幕截图_窗口 --只截取一个窗口的屏幕截图。

- 参数： title, save_path - 只读： 真

Clipboard

• get_clipboard --获取系统剪贴板的当前文本内容。

- 只读： 真

• set_clipboard --将文本复制到系统剪贴板。

- 参数： text

App Management

• launch_app --启动应用程序，并可选择等待其加载。

- 参数： command, wait_text, timeout

• get_ocr_info --获取有关活动OCR后端和可用后端的信息。

- 只读： 真

Accessibility / UI Automation (Windows)

• 获取_树 --获取焦点窗口的可访问性树。返回所有具有名称、类型和位置的交互元素。确定性和即时性。

- 参数： window_title, max_depth - 只读： 真

• 点击_元素 --使用可访问性树单击UI元素。比OCR更可靠。

- 参数： name, control_type, automation_id, window_title

• 填充_元素 --设置UI元素（例如文本框）的值。比基于OCR的填充更可靠。

- 参数： value, name, automation_id, window_title

Advanced Screen

• get_active_window --获取当前聚焦窗口的相关信息。

- 只读： 真

• 等待更改 --等待屏幕发生视觉变化。拍摄基线截图，轮询直到不同。

- 参数： timeout, poll_interval

Python库

OSWright还作为一个独立的Python库使用Playwright风格的API：

from oswright import OSWright

with OSWright() as ow:
    screen = ow.screen()
    screen.click(text="Start")
    screen.type_text("Hello World")
    screen.press("Ctrl+S")
    screen.screenshot("desktop.png")

看 示例/ 目录了解更多。

建筑

oswright/
  __init__.py          # Package entry point
  core.py              # OSWright class (= Browser)
  screen.py            # Screen class (= Page)
  locator.py           # Locator + Assertions (= Locator + expect)
  capture.py           # Screen capture (mss - cross-platform)
  detect.py            # OCR dispatcher with caching (auto-selects best backend)
  _ocr_windows.py      # Windows OCR backend (instant, built-in)
  accessibility.py     # Windows UI Automation (deterministic element finding)
  cache.py             # Screenshot diffing, image hashing, OCR result cache
  input.py             # Platform dispatcher for input backends
  _input_windows.py    # Windows input backend (Win32 API)
  _input_pynput.py     # Linux/macOS input backend (pynput)
  window.py            # Window management (list, focus, close)
  clipboard.py         # Clipboard read/write (cross-platform)
  mcp_server.py        # MCP server (35+ tools for AI agents)
tests/
  test_core.py         # 22 automated tests

许可证

麻省理工学院