PyMCPAutoGUI

想象一下，你正在编写一个AI助手，它不仅能和你聊天，还能真正帮你操作电脑上的任何软件——自动填写表格、点击按钮、甚至打开特定的窗口。今天要介绍的开源项目PyMCPAutoGUI，就能让你的AI获得这种“动手能力”。它是一个图形用户界面操作MCP服务器，基于经典的PyAutoGUI库构建，让你的AI可以像真人一样控制鼠标和键盘。

项目基本信息

一、项目介绍

PyMCPAutoGUI是一个基于Python开发的MCP服务器，它封装了强大的PyAutoGUI和PyGetWindow库，并通过MCP协议将这些功能暴露给AI客户端。简单来说，它让你的AI助手能够“看到”电脑屏幕、移动鼠标、点击按钮、输入文字，甚至管理应用程序窗口。

这个项目的设计理念是“超级简单”（It's that easy）。你只需要在终端运行一条命令，就能启动一个MCP服务器，然后你的Cursor编辑器或其他MCP客户端就可以通过自然语言来调用各种GUI自动化功能。它支持的平台包括Windows、macOS和Linux，真正做到了跨平台。

二、核心优势

开源免费且采用MIT协议

项目采用宽松的MIT开源协议，代码完全公开。你可以自由地使用、修改、甚至集成到商业项目中，无需担心法律问题。

赋能AI智能体

这是项目的核心价值所在。它赋予了AI操作本地图形界面的能力，让AI从“只能处理文本”升级到“能操作任何桌面软件”。

简单集成

与Cursor编辑器等MCP客户端的集成非常顺畅。你只需要在配置文件中添加几行代码，就能在聊天框中直接调用各种自动化工具。

全面的控制能力

基于久经考验的PyAutoGUI和PyGetWindow库，项目提供了丰富的功能：

• 鼠标控制（移动、点击、拖拽、滚动）
• 键盘控制（输入文字、按下组合键）
• 屏幕截图与图像定位（让AI能“看到”按钮位置）
• 窗口管理（激活、最小化、移动、调整大小）
• 用户交互对话框（弹窗提示、确认、输入框）

跨平台支持

无论是Windows、macOS还是Linux，PyMCPAutoGUI都能正常运行。不过在不同平台上可能需要安装一些额外的系统依赖（例如Linux上需要scrot来支持截图功能）。

三、适用场景

开发者学习和参考

对于想学习如何将Python库封装成MCP服务器的开发者，这是一个极佳的入门范例。项目结构清晰，代码量不大，非常适合阅读和研究。

个人项目使用和集成

如果你正在开发一个需要自动化操作桌面应用的AI项目，可以直接集成PyMCPAutoGUI。例如：

• 一个能够自动填写报销单的财务助手
• 一个能帮你批量重命名文件的文件管理工具
• 一个能自动截取特定区域并保存的截图工具

企业级应用开发

在企业环境中，可以用它来构建GUI自动化测试框架。例如，对内部桌面应用进行回归测试，或者自动化那些没有API接口的遗留系统。

日常工作和效率提升

对于普通用户，可以通过AI助手来自动化各种重复性操作：

• “帮我打开计算器，然后输入123*456”
• “把当前活动窗口移动到屏幕左上角”
• “截取整个屏幕并保存到桌面”

四、安装教程

系统要求

详细安装步骤

第一步：创建虚拟环境（强烈推荐）

使用虚拟环境可以避免污染全局Python环境，也让依赖管理更清晰。

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境 (Windows)
.venv\Scripts\activate

# 激活虚拟环境 (macOS/Linux)
source .venv/bin/activate

第二步：安装PyMCPAutoGUI包

有两种安装方式，推荐从PyPI安装：

# 方式一：从PyPI安装（推荐）
pip install pymcpautogui

# 方式二：从源码安装（适合想修改代码的用户）
git clone https://github.com/kitfactory/PyMCPAutoGUI.git
cd PyMCPAutoGUI
pip install .

注意：pyautogui在某些Linux系统上可能需要额外的依赖来支持截图功能，例如scrot。请参考PyAutoGUI官方文档进行相应安装。

第三步：启动MCP服务器

安装完成后，你可以直接在终端中启动服务器：

# 确保虚拟环境已激活
python -m pymcpautogui.server

如果一切正常，你会看到类似以下的输出：

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

保持这个终端窗口运行，服务器就在后台待命了。

第四步：配置Cursor编辑器（可选）

如果你使用Cursor编辑器，可以按照以下步骤集成：

1. 打开Cursor的命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）
2. 输入并选择“MCP: Open mcp.json configuration file”
3. 在打开的mcp.json文件中添加以下配置：

{
  "mcpServers": {
    "PyMCPAutoGUI": {
      "cwd": "${workspaceFolder}",
      "command": "python",
      "args": ["-m", "pymcpautogui.server"]
    }
  }
}

注意：如果你的虚拟环境不在默认路径，可能需要将command改为虚拟环境中Python的完整路径，例如.venv/bin/python（macOS/Linux）或.venv\\Scripts\\python.exe（Windows）。

4. 保存文件，Cursor会自动检测到新的MCP服务器。

五、使用示例

配置完成后，你就可以在MCP客户端中通过自然语言或直接调用工具来使用PyMCPAutoGUI的功能了。

示例1：鼠标操作

在Cursor中使用：输入 @PyMCPAutoGUI move_to(x=500, y=300)，AI助手就会调用工具将鼠标移动到屏幕坐标(500, 300)的位置。

更复杂的操作：@PyMCPAutoGUI click(button='right', clicks=2) 会在当前位置执行鼠标右键双击。

示例2：键盘操作

输入文字：@PyMCPAutoGUI write(text='Hello from AI!', interval=0.05) 会以每个字符0.05秒的间隔输入文字，模拟真实打字效果。

按下组合键：@PyMCPAutoGUI hotkey(keys=['ctrl', 'c']) 会执行复制操作（Ctrl+C）。

示例3：截图与图像识别

截取整个屏幕：@PyMCPAutoGUI screenshot(filename='my_screenshot.png')

在屏幕上查找图像：假设你有一个按钮的截图button.png，你可以让AI找到它的位置：@PyMCPAutoGUI locate_center_on_screenshot(image_path='button.png') 这会返回按钮的中心坐标，然后你可以用这个坐标去点击它。

示例4：窗口管理

激活记事本窗口：@PyMCPAutoGUI activate_window(title='记事本')

获取所有窗口标题：@PyMCPAutoGUI get_all_titles() 会返回当前系统所有打开窗口的标题列表。

移动并调整窗口大小：@PyMCPAutoGUI move_window(title='Chrome', x=0, y=0) 和 @PyMCPAutoGUI resize_window(title='Chrome', width=800, height=600)

示例5：用户交互对话框

弹出提示框：@PyMCPAutoGUI alert(text='任务已完成！', title='AI助手')

获取用户输入：@PyMCPAutoGUI prompt(text='请输入你的名字：', title='身份验证') 会弹出一个输入框，用户输入的内容会被返回给AI。

完整自动化流程示例

假设你想让AI自动打开记事本，输入一段文字，然后保存文件。你可以在Cursor中连续发送以下指令：

@PyMCPAutoGUI press(key='win')
@PyMCPAutoGUI write(text='notepad', interval=0.05)
@PyMCPAutoGUI press(key='enter')
@PyMCPAutoGUI write(text='This is a test file created by AI.', interval=0.05)
@PyMCPAutoGUI hotkey(keys=['ctrl', 's'])

当然，更高级的做法是编写一个Python脚本，通过MCP客户端库来批量调用这些工具。

六、常见问题

问题1：启动服务器时提示“ModuleNotFoundError: No module named 'pymcpautogui'”

解决方案：请确保你已经激活了虚拟环境，并且在该环境中执行了pip install pymcpautogui。可以用pip list命令检查包是否安装成功。

问题2：在Linux上运行时截图功能报错

解决方案：PyAutoGUI在Linux上需要额外的截图工具。对于基于Debian/Ubuntu的系统，运行sudo apt-get install scrot。对于其他发行版，请参考PyAutoGUI文档安装对应的截图工具。

问题3：Cursor中无法调用PyMCPAutoGUI工具

解决方案：

• 确认mcp.json中的配置是否正确，特别是command和args的路径。
• 检查PyMCPAutoGUI服务器是否在终端中正常运行（看到“Uvicorn running on...”字样）。
• 尝试重启Cursor编辑器。

问题4：鼠标或键盘操作没有反应

解决方案：

• 某些操作系统（如macOS）需要为终端或Cursor授予辅助功能权限。请前往系统设置中的“隐私与安全性”->“辅助功能”，添加你的终端应用或Cursor。
• 检查是否有其他程序拦截了鼠标/键盘输入。

问题5：如何临时禁用PyMCPAutoGUI的快速操作？

解决方案：PyAutoGUI有一个故障安全机制。如果你发现AI在乱动鼠标，可以快速将鼠标移动到屏幕的四个角落之一（通常是左上角），这会触发一个pyautogui.FailSafeException异常，从而停止所有操作。你也可以通过@PyMCPAutoGUI set_failsafe(failsafe=True)来启用或禁用这个功能。

七、总结

PyMCPAutoGUI是一个简洁而强大的工具，它巧妙地连接了AI语言模型和桌面图形界面。通过MCP协议，它让AI助手获得了直接操作电脑的能力，从而打开了无数自动化应用的大门。

这个项目的最大亮点就是“简单”：安装简单、配置简单、使用简单。你不需要学习复杂的自动化脚本语法，只需要用自然语言告诉AI你想做什么。虽然目前它只有19颗星，还是一个相对年轻的项目，但它的潜力巨大。

如果你经常需要执行重复性的桌面操作，或者正在开发一个需要与GUI交互的AI应用，强烈建议你尝试一下PyMCPAutoGUI。 只需几分钟配置，你就能体验到让AI替你操作电脑的乐趣。