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

增强你的 AI Agent 的能力！ ✨ PyMCPAutoGUI 在你的 AI agent（例如 Cursor 或其他 MCP 兼容环境中的 agent）和你的计算机图形用户界面 (GUI) 之间架起了一座桥梁。它允许你的 agent 看到屏幕 👁️，控制鼠标 🖱️ 和键盘 ⌨️，并像人类用户一样与窗口 🪟 交互！

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

🤔 为什么选择 PyMCPAutoGUI？

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

🛠️ 支持的环境

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

🚀 快速入门 - 非常简单！

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

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

# 创建并激活一个虚拟环境（使用 venv 的示例）
python -m venv .venv
# Windows PowerShell
.venv\Scripts\Activate.ps1
# macOS / Linux bash
source .venv/bin/activate

# 使用 pip 安装（从 PyPI 或本地源）
# 确保你的虚拟环境已激活！
pip install pymcpautogui # 或者如果从本地源安装，则 pip install .

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

2. 运行 MCP 服务器

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

# 确保你的虚拟环境已激活！
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: Open mcp.json configuration file"。

2. 添加 PyMCPAutoGUI 配置： 将此配置添加到你的 mcp.json 中或与之合并。如果需要，调整路径（尤其是在 Cursor 不是从项目根目录运行的情况下）。

   {
       "mcpServers": {
           // ... 其他 MCP 服务器配置（如果有）...
           "PyMCPAutoGUI": {
               // 设置工作目录。${workspaceFolder} 通常是正确的。
               "cwd": "${workspaceFolder}",
   
               // 运行 Python 的命令。如果 venv 在启动 Cursor 的终端中处于活动状态，则 'python' 有效
               // 或者指定完整路径。
               "command": "python", // 或者 ".venv/Scripts/python.exe" (Win) 或 ".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='Automating with AI! 🎉', interval=0.1) @PyMCPAutoGUI screenshot(filename='current_screen.png') @PyMCPAutoGUI activate_window(title='Notepad')

🧰 可用工具

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 文件。 祝你自动化愉快！ 😄