使用说明

macos控制mcp

给AI代理 眼睛和手 在macOS上。

这是什么？

一 MCP服务器让AI代理 查看屏幕，阅读屏幕上的文本，并进行交互 --点击、打字、滚动——就像坐在键盘前的人一样。与盲脚本运行器不同，此MCP为代理提供 国家意识：他们对屏幕进行截图，OCR以获取带有像素坐标的文本，然后在需要的地方点击。

See Think Act循环

┌─────────────────────────────────────────────────┐
│                                                 │
│   1. SEE        screenshot / screen_ocr         │
│      ↓          "What's on the screen?"         │
│                                                 │
│   2. THINK      AI reasons about the content    │
│      ↓          "I need to click the Save btn"  │
│                                                 │
│   3. ACT        click_at / type_text / press_key│
│                 "Click at (425, 300)"           │
│                                                 │
│      ↻ repeat                                   │
└─────────────────────────────────────────────────┘

这就是它强大的原因：代理看见每个操作的结果，可以纠正、重试或继续前进——就像你一样。

快速开始

无需安装--直接使用npx运行：

npx -y macos-control-mcp

首次运行时，Python虚拟环境会在以下位置自动创建 ~/.macos-control-mcp/.venv 使用所需的Apple Vision和Quartz框架。一次大约需要60秒，并在更新过程中持续存在。

MCP视频展示：

https://www.youtube.com/watch?v=aswlsElHV5o

配置您的AI客户端

所有客户端都使用相同的命令： npx -y macos-control-mcp

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "macos-control": {
      "command": "npx",
      "args": ["-y", "macos-control-mcp"]
    }
  }
}

保存后重新启动Claude Desktop。

Claude Code

claude mcp add macos-control -- npx -y macos-control-mcp

VS Code / GitHub Copilot

增添 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "macos-control": {
      "command": "npx",
      "args": ["-y", "macos-control-mcp"]
    }
  }
}

Cursor

增添 .cursor/mcp.json 在您的项目中：

{
  "mcpServers": {
    "macos-control": {
      "command": "npx",
      "args": ["-y", "macos-control-mcp"]
    }
  }
}

Cline

打开Cline扩展设置→ MCP服务器→ Add:

{
  "macos-control": {
    "command": "npx",
    "args": ["-y", "macos-control-mcp"]
  }
}

Windsurf

增添 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "macos-control": {
      "command": "npx",
      "args": ["-y", "macos-control-mcp"]
    }
  }
}

权限

macOS需要两个权限才能实现完整功能：

屏幕录制 --用于截图和OCR
无障碍 --用于单击、键入和读取UI元素

首选 系统设置→ 隐私和安全 并将您的终端应用程序（终端、iTerm2、VS Code等）添加到这两个列表中。首次使用时会提示您。

工具（19）

查看屏幕

工具	说明
`screenshot`	以JPEG格式捕获全屏或应用程序窗口
`screen_ocr`	OCR屏幕--返回具有像素坐标的文本元素
`find_text_on_screen`	查找特定文本并获得可点击的x、y坐标

与屏幕互动

工具	说明
`click_at`	点击x，y坐标（返回截图）
`double_click_at`	在x、y处双击（返回屏幕截图）
`type_text`	在最前面的应用程序中键入文本
`press_key`	按组合键（Cmd+S、Ctrl+C等）
`scroll`	向上/向下/向左/向右滚动

应用管理

工具	说明
`launch_app`	打开或聚焦应用程序
`list_running_apps`	列出可见的正在运行的应用程序

可访问性树

工具	说明
`get_ui_elements`	获取应用程序窗口的可访问性树
`click_element`	单击一个命名的UI元素（返回屏幕截图）

浏览器自动化

工具	说明
`execute_javascript`	在活动浏览器选项卡中运行JavaScript
`get_page_text`	从页面获取所有可见文本（比OCR更快）
`click_web_element`	通过CSS选择器点击元素（即时、精确）
`fill_form_field`	使用CSS选择器填充表单字段

公用事业

工具	说明
`open_url`	在Safari或Chrome中打开URL
`get_clipboard`	读取剪贴板内容
`set_clipboard`	写入剪贴板

示例工作流

填写网络表单

You: "Go to example.com/signup and fill in my details"

Agent:
1. open_url("https://example.com/signup")
2. screenshot() → sees the form
3. screen_ocr() → finds "Email" field at (300, 250)
4. click_at(300, 250) → clicks the email field
5. type_text("user@example.com")
6. find_text_on_screen("Submit") → gets button coordinates
7. click_at(350, 500) → submits the form
8. screenshot() → confirms success

浏览不熟悉的应用程序

You: "Change the font size to 16 in TextEdit"

Agent:
1. launch_app("TextEdit")
2. screenshot() → sees the app
3. get_ui_elements("TextEdit") → finds menu items
4. press_key("t", ["command"]) → opens Fonts panel
5. screenshot() → sees the font panel
6. find_text_on_screen("Size") → locates the size field
7. click_at(x, y) → clicks size field
8. type_text("16")
9. press_key("return")

从电子邮件中提取信息

You: "Copy the tracking number from the shipping email in Mail"

Agent:
1. launch_app("Mail")
2. screenshot() → sees the inbox
3. find_text_on_screen("Your order has shipped") → locates the email
4. click_at(x, y) → opens the email
5. screenshot() → sees the email content
6. screen_ocr() → extracts all text including tracking number
7. set_clipboard("1Z999AA10123456784") → copies to clipboard

截图并描述屏幕上的内容

You: "What do I have open right now?"

Agent:
1. screenshot() → captures the full screen
2. Describes what it sees: apps, windows, content
3. list_running_apps() → ["Safari", "Slack", "VS Code", "Spotify"]
4. "You have Safari open on Twitter, Slack with 3 unread messages, and VS Code editing index.ts"

调试UI问题

You: "The submit button on this page isn't working, can you check what's happening?"

Agent:
1. screenshot() → sees the page
2. find_text_on_screen("Submit") → locates button at (500, 600)
3. get_ui_elements("Safari") → inspects accessibility tree
4. "The button has aria-disabled=true. There's a required field 'Phone' that's empty."
5. find_text_on_screen("Phone") → locates the field
6. click_at(x, y) → clicks the field
7. type_text("+1 555-0123")
8. click_at(500, 600) → clicks Submit again
9. screenshot() → confirms it worked

控制Spotify

You: "Pause the music and turn the volume down"

Agent:
1. launch_app("Spotify")
2. screenshot() → sees Spotify is playing
3. find_text_on_screen("Pause") → locates pause button
4. click_at(x, y) → pauses playback
5. find_text_on_screen("Volume") → locates volume slider area
6. click_at(x, y) → adjusts volume
7. screenshot() → confirms paused and volume lowered

使用Finder

You: "Create a new folder on my Desktop called 'Project Assets' and move it to Documents"

Agent:
1. launch_app("Finder")
2. press_key("d", ["command", "shift"]) → opens Desktop
3. screenshot() → sees Desktop in Finder
4. press_key("n", ["command", "shift"]) → creates new folder
5. type_text("Project Assets")
6. press_key("return")
7. screenshot() → confirms folder created

在Slack中发送消息

You: "Send 'build is green, ready to deploy' in the #engineering channel on Slack"

Agent:
1. launch_app("Slack")
2. screenshot() → sees Slack
3. press_key("k", ["command"]) → opens Quick Switcher
4. type_text("engineering")
5. press_key("return") → opens #engineering
6. screenshot() → confirms channel is open
7. click_at(x, y) → clicks message input
8. type_text("build is green, ready to deploy")
9. press_key("return") → sends message
10. screenshot() → confirms sent

从网站上研究和复制数据

You: "Look up the current price of AAPL on Google Finance and copy it"

Agent:
1. open_url("https://google.com/finance/quote/AAPL:NASDAQ")
2. screenshot() → sees the page loading
3. screen_ocr() → reads all text on the page
4. Finds the price: "$187.42"
5. set_clipboard("$187.42")
6. "Copied AAPL price $187.42 to your clipboard"

多应用工作流程

You: "Take what's in my clipboard, search for it in Safari, and screenshot the results"

Agent:
1. get_clipboard() → "best mechanical keyboards 2025"
2. launch_app("Safari")
3. press_key("l", ["command"]) → focuses address bar
4. type_text("best mechanical keyboards 2025")
5. press_key("return") → searches
6. screenshot() → captures the search results
7. "Here are the search results for 'best mechanical keyboards 2025'"

导航系统设置

You: "Turn on Dark Mode"

Agent:
1. launch_app("System Settings")
2. screenshot() → sees System Settings
3. find_text_on_screen("Appearance") → locates the option
4. click_at(x, y) → opens Appearance settings
5. screenshot() → sees Light/Dark/Auto options
6. find_text_on_screen("Dark") → locates Dark mode option
7. click_at(x, y) → enables Dark Mode
8. screenshot() → confirms Dark Mode is on

需求

macOS 13+ （文图拉或更高版本）
Node.js 18+
Python 3.9+ （预装在macOS上——需要OCR和鼠标控制）

运作原理

截图 --本地人 screencapture 命令行界面
光学字符识别 --Apple Vision框架（VNRecognizeTextRequest）通过Python桥返回带有边界框坐标的文本
老鼠 --Quartz Core Graphics事件通过Python桥实现精确的像素级控制
键盘和应用程序 --AppleScript通过 osascript 用于按键、应用程序启动和UI元素交互
Python环境 --自动管理的venv at ~/.macos-control-mcp/.venv/ 只有两个包裹(pyobjc-framework-Vision, pyobjc-framework-Quartz)

故障排除

“权限被拒绝”或空白截图 → 将您的终端添加到系统设置→ 隐私和安全→ 屏幕录制

点击不起作用 → 将您的终端添加到系统设置→ 隐私和安全→ 无障碍

Python安装失败 → 确保 python3 在你的路径。跑 python3 --version 检查。没有它，非Python工具（键盘、应用程序、剪贴板）仍然可以工作。

OCR返回空结果 → 确保已授予“屏幕录制”权限。首先尝试全屏OCR（不使用 app 参数）。

“找不到应用程序”错误 → 使用活动监视器中显示的确切应用程序名称（例如，“Google Chrome”而不是“Chrome”）。

许可证

麻省理工学院