PyMCPAutoGUI 🖱️⌨️🖼️ - 通过 MCP 实现 GUI 自动化

增强您的 AI 代理的能力！ ✨ PyMCPAutoGUI 为您的 AI 代理（如 Cursor 或其他与 MCP 兼容的环境中的代理）和计算机的图形用户界面 (GUI) 之间提供了一个桥梁。它允许您的代理查看屏幕 👁️、控制鼠标 🖱️ 和键盘 ⌨️，并像人类用户一样与窗口 🪟 交互！

停止繁琐的手动 GUI 任务，让您的 AI 为您分担重任 💪。非常适合自动化重复性操作、测试 GUI 或构建强大的 AI 助手 🤖。

🤔 为什么选择 PyMCPAutoGUI？

• 🤖 赋予您的代理力量： 让您的 AI 代理能够直接与桌面应用程序交互。
• ✅ 简单集成： 与 Cursor 编辑器等与 MCP 兼容的客户端无缝协作。即插即用！
• 🚀 易于使用： 通过一个简单的服务器命令即可开始使用。真的 就是这么简单。
• 🖱️⌨️ 全面控制： 提供了从经过实战考验的 PyAutoGUI 和 PyGetWindow 中广泛范围的 GUI 自动化功能。
• 🖼️ 屏幕感知： 包含截屏和在屏幕上定位图像的工具 – 让您的代理 看见！
• 🪟 窗口管理： 控制窗口的位置、大小、状态（最小化、最大化）等。整理好你的桌面！
• 💬 用户交互： 显示警报、确认和提示框以与用户交流。

🛠️ 支持的环境

• 操作系统： Windows、macOS、Linux（每个操作系统上需要 pyautogui 的适当依赖项）
• Python： 3.11+ 🐍
• MCP 客户端： Cursor 编辑器、支持 模型上下文协议 (MCP) 的任何客户端

🚀 开始使用 - 非常简单！

1. 安装（推荐：使用虚拟环境！）

使用虚拟环境可以让您的项目依赖保持整洁。

# Create and activate a virtual environment (example using venv)
python -m venv .venv
# Windows PowerShell
.venv\Scripts\Activate.ps1
# macOS / Linux bash
source .venv/bin/activate

# Install using pip (from PyPI or local source)
# Make sure your virtual environment is active!
pip install pymcpautogui # Or pip install . if installing from local source

（注意：pyautogui 可能有系统依赖项，例如 Linux 上用于截屏的 scrot。请查阅 pyautogui 文档以了解特定于操作系统的安装要求。）

2. 运行 MCP 服务器

安装完成后，只需从终端运行服务器：

# Make sure your virtual environment is activated!
python -m pymcpautogui.server

服务器将启动并监听连接（默认端口为 6789）。查找如下输出：

INFO:     Started server process [XXXXX]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:6789 (Press CTRL+C to quit)

在需要 GUI 自动化时，请保持此终端运行！✨

✨ 与 Cursor 编辑器无缝集成

将 PyMCPAutoGUI 连接到 Cursor (@ 符号)，以便在您的编码工作流中直接进行 GUI 自动化。

1. 打开 MCP 配置： 在 Cursor 中，使用命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）并找到 "MCP: 打开 mcp.json 配置文件"。

2. 添加 PyMCPAutoGUI 配置： 将此配置添加或合并到您的 mcp.json 中。如果需要，请调整路径（特别是当 Cursor 不是从项目根目录运行时）。

   {
       "mcpServers": {
           // ... 其他 MCP 服务器配置 ...
           "PyMCPAutoGUI": {
               // 设置工作目录。${workspaceFolder} 通常是正确的。
               "cwd": "${workspaceFolder}",
   
               // 运行 Python 的命令。如果终端中激活了虚拟环境，则 'python' 可以工作；
               // 否则请指定完整路径。
               "command": "python", // 或者 ".venv/Scripts/python.exe" (Windows) 或 ".venv/bin/python" (Mac/Linux)
   
               // 启动服务器模块的参数。
               "args": ["-m", "pymcpautogui.server"]
           }
           // ... 其他 MCP 服务器配置 ...
       }
   }
   

   （提示：如果 mcp.json 已经存在，只需将 "PyMCPAutoGUI": { ... } 部分添加到 mcpServers 对象内即可。）

3. 保存 mcp.json。Cursor 将会检测到服务器。

4. 自动化！ 在 Cursor 聊天中使用 @PyMCPAutoGUI：

   示例：
   @PyMCPAutoGUI move_to(x=100, y=200)
@PyMCPAutoGUI write(text='通过 AI 自动化！🎉', interval=0.1)
@PyMCPAutoGUI screenshot(filename='current_screen.png')
@PyMCPAutoGUI activate_window(title='记事本')

🧰 可用工具

PyMCPAutoGUI 暴露了来自 pyautogui 和 pygetwindow 的大多数功能。示例如下：

• 鼠标 🖱️： move_to, click, move_rel, drag_to, drag_rel, scroll, mouse_down, mouse_up, get_position
• 键盘 ⌨️： write, press, key_down, key_up, hotkey
• 截图 🖼️： screenshot, locate_on_screen, locate_center_on_screen
• 窗口 🪟： get_all_titles, get_windows_with_title, get_active_window, activate_window, minimize_window, maximize_window, restore_window, move_window, resize_window, close_window
• 对话框 💬： alert, confirm, prompt, password
• 配置 ⚙️： set_pause, set_failsafe

完整的列表和详细信息，请查看 pymcpautogui/server.py 文件或在您的 MCP 客户端中使用 @PyMCPAutoGUI list_tools 命令。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。愉快地自动化吧！😄