PyMCPAutoGUI 🖱️⌨️🖼️ - GUI Automation via MCP

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

增强 AI Agent 的能力！ ✨ PyMCPAutoGUI 在你的 AI Agent（例如 Cursor 中的 Agent 或其他兼容 MCP 的环境中的 Agent）与计算机的图形用户界面（GUI）之间搭建桥梁。它让 Agent 可以查看屏幕 👁️、控制鼠标 🖱️ 和键盘 ⌨️，并与窗口 🪟 交互，就像真人用户一样！

告别繁琐的手动 GUI 操作，让 AI 为你承担繁重的工作 💪。它非常适合自动化重复操作、测试 GUI 或构建强大的 AI 助手 🤖。

🤔 为什么选择 PyMCPAutoGUI？

• 🤖 赋能 Agent： 让 AI Agent 能够直接与桌面应用交互。
• ✅ 简单集成： 可与 Cursor 编辑器等兼容 MCP 的客户端无缝协作，即装即用！
• 🚀 易于使用： 只需运行一条简单的服务命令即可开始。没错，就是这么简单。
• 🖱️⌨️ 全面控制： 提供丰富的 GUI 自动化功能，基于久经考验的 PyAutoGUI 和 PyGetWindow。
• 🖼️ 屏幕感知： 提供截屏和在屏幕上定位图像的工具，让 Agent 看见 屏幕！
• 🪟 窗口管理： 控制窗口位置、大小和状态（最小化、最大化）等。让桌面井井有条！
• 💬 用户交互： 显示警告、确认和提示框，以便与用户沟通。

🛠️ 支持的环境

• 操作系统： Windows、macOS、Linux（各操作系统上的 pyautogui 需要相应依赖项）
• Python： 3.11+ 🐍
• MCP 客户端： Cursor 编辑器，以及任何支持 Model Context Protocol (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: Open mcp.json configuration file”。

2. 添加 PyMCPAutoGUI 配置： 将此配置添加到或合并到你的 mcp.json 中。必要时调整路径（特别是 Cursor 并非从项目根目录启动时）。

   {
       "mcpServers": {
           // ... other MCP server configs if any ...
           "PyMCPAutoGUI": {
               // Sets the working directory. ${workspaceFolder} is usually correct.
               "cwd": "${workspaceFolder}",
   
               // Command to run Python. 'python' works if the venv is active in the terminal
               // where Cursor was launched, or specify the full path.
               "command": "python", // Or ".venv/Scripts/python.exe" (Win) or ".venv/bin/python" (Mac/Linux)
   
               // Arguments to start the server module.
               "args": ["-m", "pymcpautogui.server"]
           }
           // ... other MCP server configs if any ...
       }
   }
   

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

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 许可，详情请参阅 LICENSE 文件。祝自动化愉快！😄