Control MCP

控制MCP-鼠标控制服务器

一种模型上下文协议（MCP）服务器，在macOS上提供低级鼠标控制功能。此服务器允许您使用Python的pyautogui库控制光标位置、执行单击、拖动操作、滚动和截图。

特性

• 获取光标位置：检索当前鼠标坐标
• 移动光标：通过可选的平滑移动移动到特定的屏幕坐标
• 点击：在任何位置执行左、右或中单击（单击或多次单击）
• 拖拽：从一个位置拖动到另一个位置
• 滚动：在任何位置向上或向下滚动
• 获取屏幕尺寸：获取屏幕尺寸
• 截图：将整个屏幕或特定区域捕获为PNG图像

安装

1. 安装依赖项:

   cd /Users/kylesullivan/Documents/coding_projects/control-mcp
   pip install -e .

1. 授予访问权限:

- 首选 系统首选项>安全与隐私>隐私>辅助功能 - 添加并启用您正在使用的终端应用程序或Python可执行文件 - 这是macOS上鼠标控件工作所必需的

配置

将此MCP服务器添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "control-mcp": {
      "command": "python3",
      "args": [
        "-m",
        "control_mcp.server"
      ]
    }
  }
}

更新配置后，重新启动Claude Desktop。

可用工具

1.get_cursor_position

获取屏幕上的当前光标位置。

参数：无

示例:

Use get_cursor_position to find where my mouse is

2.move_cursor

将光标移动到指定坐标。

参数:

• x （数字，必填）：X坐标，从左开始以像素为单位
• y （数字，必填）：从顶部开始的Y坐标（像素）
• duration （数字，可选）：移动持续时间（秒）（0表示瞬间，默认值：0）

示例:

Move the cursor to position x=500, y=300 with a smooth 1 second movement

3.点击

在当前位置或指定坐标处执行鼠标单击。

参数:

• x （数字，可选）：X坐标
• y （数字，可选）：Y坐标
• button （字符串，可选）：“left”、“right”或“middle”（默认值：“left）
• clicks （数字，可选）：点击次数，双击使用2（默认值：1）
• interval （数字，可选）：两次点击之间的时间（秒）（默认值：0.1）

示例:

Click at position x=100, y=200
Double-click at x=300, y=400
Right-click at the current cursor position

4.拖动

从一个位置拖动到另一个位置。

参数:

• from_x （数字，必填）：起始X坐标
• from_y （数字，必填）：起始Y坐标
• to_x （数字，必填）：结束X坐标
• to_y （数字，必填）：结束Y坐标
• duration （数字，可选）：拖动持续时间（秒）（默认值：0.5）
• button （字符串，可选）：“left”、“right”或“middle”（默认值：“left）

示例:

Drag from position (100, 100) to (300, 300) over 1 second

5.滚动

在当前或指定的光标位置滚动。

参数:

• amount （数字，必填）：滚动金额（正=向上，负=向下）
• x （数字，可选）：可滚动的X坐标
• y （数字，可选）：可滚动的Y坐标

示例:

Scroll up by 5 clicks at position x=500, y=500
Scroll down by 10 clicks at the current position

6.get_screen_size

获取屏幕尺寸。

参数：无

示例:

What is my screen size?

7.截图

将整个屏幕或特定区域捕获为PNG图像。

参数:

• region （数组，可选）：要捕获的区域 [x, y, width, height]

- x：左上角的X坐标 - y：左上角的Y坐标 - width：区域的宽度（像素） - height：区域的高度（像素） - 如果没有提供，则捕获整个屏幕

示例:

Take a screenshot of the entire screen
Take a screenshot of the region starting at (100, 100) with width 800 and height 600

退货：Claude可以显示的base64格式的PNG图像

安全特性

• 故障保护：将鼠标移动到屏幕的任何角落以中止操作
• 边界检查：所有坐标均根据屏幕尺寸进行验证
• 错误处理：清除无效输入的错误消息
• 在操作之间暂停：操作之间的延迟很小（0.1秒），以防止出现问题

克劳德决定如何使用这些工具

Claude会根据您的要求自动选择使用这些工具。工具描述包含关键字，可帮助Claude识别何时使用它们。以下是触发克劳德使用鼠标控制工具的短语：

触发短语（克劳德会认出这些）

获得更好结果的提示

1. 让克劳德先看看：“截取屏幕截图并单击设置按钮”
2. 具体行动：上下文菜单的“双击”与“单击”、“右键单击”
3. 参考UI元素：“单击蓝色提交按钮”可帮助Claude在屏幕截图中找到它
4. 连锁行动：“截取屏幕截图，找到搜索框，然后单击它”

用法示例

在Claude Desktop中配置后，您可以让Claude控制鼠标：

1. 查看您的屏幕:

   Take a screenshot and tell me what apps are open

1. 点击某物:

   Take a screenshot and click on the Safari icon in the dock

1. 查找光标位置:

   Where is my mouse cursor right now?

1. 移动并单击:

   Move the cursor to x=200, y=300 and click

1. 双击打开:

   Double-click at position x=150, y=250

1. 拖动操作:

   Drag from (100, 100) to (500, 500)

1. 滚动页面:

   Scroll down 10 clicks on the current page

1. 复杂任务:

   Take a screenshot, find the Chrome browser, and open it

故障排除

权限错误

如果您遇到权限错误：

1. 检查是否授予了辅助功能权限
2. 授予权限后重新启动Claude Desktop
3. 确保您已将权限授予正确的应用程序（终端、Python等）

边界外坐标

如果点击或移动失败：

1. 使用 get_screen_size 检查屏幕尺寸
2. 确保坐标在 0 到 screen_width-1 和 0 到 screen_height-1

未找到模块

如果您收到导入错误：

1. 确保你跑了 pip install -e . 从项目目录
2. 验证 cwd Claude Desktop配置中的路径指向 src 目录

发展

项目结构

control-mcp/
├── src/
│   └── control_mcp/
│       ├── __init__.py
│       ├── server.py          # Main MCP server
│       └── mouse_control.py   # Mouse control logic
├── pyproject.toml
├── README.md
└── claude.md

手动测试

您可以直接测试鼠标控制器：

from control_mcp.mouse_control import MouseController

mouse = MouseController()

# Get position
x, y = mouse.get_cursor_position()
print(f"Cursor at: {x}, {y}")

# Move cursor
mouse.move_cursor(500, 300)

# Click
mouse.click(100, 200)

# Take a screenshot
image_base64 = mouse.screenshot()
print(f"Screenshot taken, {len(image_base64)} bytes")

# Screenshot a specific region
region_image = mouse.screenshot(region=(100, 100, 800, 600))
print(f"Region screenshot taken")

许可证

MIT许可证

备注

• 此工具在操作系统级别提供直接鼠标控制
• 负责任地使用并注意您的点击位置
• FAILSAFE功能允许您通过将鼠标移动到屏幕角落来中止