AI导哈

鼠标控制服务

一个提供macOS系统底层鼠标控制功能的服务器，支持光标移动、点击、拖拽、滚动和截图等功能。

  • by kylesullyman
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 kylesullyman/control-mcp

使用说明

控制MCP-鼠标控制服务器

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

特性

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

安装

  1. 安装依赖项:

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

  2. 授予访问权限:

    • 首选 系统首选项>安全与隐私>隐私>辅助功能
    • 添加并启用您正在使用的终端应用程序或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识别何时使用它们。以下是触发克劳德使用鼠标控制工具的短语：

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

你说什么 克劳德将使用的工具
“单击按钮” screenshot → click
“显示屏幕上的内容” screenshot
“我的老鼠在哪里？” get_cursor_position
“将光标移动到…” move_cursor
“向下滚动页面” scroll
“将此文件拖动到…” drag
“打开该应用程序”（带屏幕截图） screenshot → move_cursor → click （双）
“我的屏幕分辨率是多少？” get_screen_size

获得更好结果的提示

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

用法示例

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

  1. 查看您的屏幕:

    Take a screenshot and tell me what apps are open

  2. 点击某物:

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

  3. 查找光标位置:

    Where is my mouse cursor right now?

  4. 移动并单击:

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

  5. 双击打开:

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

  6. 拖动操作:

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

  7. 滚动页面:

    Scroll down 10 clicks on the current page

  8. 复杂任务:

    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功能允许您通过将鼠标移动到屏幕角落来中止

相关 MCP