Mcp Osascript

io.github.m0rvayne由 GitHub 账号 m0rvayne 发布v1.1.3更新于 Nov 3, 2026

macOS automation: 17 typed tools for windows, menus, keyboard, clipboard, tabs, screenshots

已验证STDIO仅桌面浏览器自动化开发者工具

概览

AI 生成的概览

仅限 macOS 的 MCP 服务器，让助手控制 Mac：窗口、菜单、键盘、剪贴板、浏览器标签页、截图和快捷指令。

可以做什么
  • 控制应用与窗口：启动或前置应用，列出、移动、缩放、最小化、全屏或关闭窗口，隐藏、取消隐藏或退出应用，读取最前台应用与显示器布局
  • 操作菜单与输入：列出或点击菜单项、输入文本、按下组合键，以及执行任意 AppleScript 或 JXA 脚本
  • 读写剪贴板、显示系统通知、打开网址与文件或文件夹
  • 查看 Safari、Chrome 或 Arc 的标签页，截取全屏、区域或窗口截图，列出或运行 Apple 快捷指令
  • 检查已授予哪些 macOS 权限以及各自解锁的功能
适用场景
适合希望助手直接操作 Mac 的场景，例如调整窗口布局、逐级点击应用菜单、填写输入框、截图或触发快捷指令，而不只是给出说明。仅在 macOS 桌面环境中有意义。
运行要求
在 macOS 13 或更高版本上本地运行，需要 Node.js 18 或更高版本，可通过 npx 或 Claude Desktop 扩展包安装。部分工具需要在系统设置中授予自动化、辅助功能和屏幕录制权限。未声明任何 API 密钥或环境变量。
安装前请注意
run_osascript 工具会执行任意 AppleScript 或 JXA，MCP 客户端即为信任边界，被诱导执行的脚本将以你的用户权限运行。工具可以输入、点击、关闭窗口、退出应用、写入剪贴板、打开文件与网址并保存截图。屏幕录制与辅助功能权限会暴露屏幕内容和输入控制。作者自行委托的红队审计并非第三方认证。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Mcp Osascript，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

[mcp-osascript]

Let Claude control your Mac. Move windows, click menus, type text, read clipboard, manage browser tabs, take screenshots, run Shortcuts — 18 typed tools with input validation and security guardrails.

[npm version] [macOS 13+] [Node 18+] [License: MIT] [Tests: 84 passed] [Tests] [m0rvayne/mcp-osascript MCP server]

Listed in the official MCP Registry as io.github.m0rvayne/mcp-osascript

[Demo]

Quick Start

Claude Desktop — one click. Download mcp-osascript-1.1.3.mcpb from the latest release and double-click it. Claude Desktop installs the extension itself.

Or add it to the config manually:

json
{  "mcpServers": {    "osascript": {      "command": "npx",      "args": ["-y", "mcp-osascript"]    }  }}

Add this to your Claude Desktop config (Settings → Developer → Edit Config), restart Claude, and you're ready.

Config for other clients (Cursor, VS Code, Claude Code)

Cursor / VS Code (Copilot)

json
{  "mcpServers": {    "osascript": {      "command": "npx",      "args": ["-y", "mcp-osascript"]    }  }}

Claude Code

bash
claude mcp add osascript -- npx -y mcp-osascript

From source (development)

bash
git clone https://github.com/m0rvayne/mcp-osascript.gitcd mcp-osascript && npm install# then use: "command": "node", "args": ["/path/to/mcp-osascript/server/index.js"]

Try These Prompts

Once installed, ask Claude:

PromptWhat happens
"Open Safari and show me what tabs I have"Launches Safari, reads all tab titles and URLs
"Move the Finder window to the left half of my screen"Resizes and positions the window
"Click File → Export as PDF in Keynote"Navigates the menu bar and clicks the item
"Copy the URL from my active Chrome tab"Reads browser tabs, finds the active one
"Type 'Hello World' into the active text field"Simulates keyboard input
"Show a notification when you're done"Displays a native macOS banner
"What app am I using right now?"Returns the frontmost app name and bundle ID
"Press Cmd+Shift+4"Triggers the screenshot shortcut
"List all items in the Edit menu of VS Code"Introspects the menu bar
"Close the second window of Terminal"Targets a specific window by index
"Screenshot the Safari window and save it to my Desktop"Captures just that window, not the whole screen
"Which monitor is my Slack window on?"Reads display geometry and window positions
"Hide everything except my editor"Hides apps without quitting them
"Run my 'Daily Standup' shortcut"Invokes an Apple Shortcut by name

Tools

18 typed tools, each with input validation, error classification, and permission-aware error messages.

ToolWhat it doesPermission
check_permissionsReport which permissions are granted and what each unlocksNone
run_osascriptExecute any AppleScript or JXA scriptNone
get_clipboardRead clipboard as textNone
set_clipboardWrite text to clipboardNone
send_notificationShow macOS notification bannerNone
open_urlOpen URL in browser (http/https/mailto only)None
open_appLaunch or bring app to frontNone
get_frontmost_appGet active app name + bundle IDAutomation
get_browser_tabsList tabs in Safari, Chrome, or ArcAutomation
type_textType text into active app (max 500 chars)Accessibility
press_keyPress key with modifiers (cmd+c, return, f5)Accessibility
manage_windowsList / move / resize / minimize / fullscreen / closeAccessibility
get_displaysList monitors — position, size, which is mainNone
app_menuList or click menu items in any appAccessibility
screenshotCapture full screen, a region, or an app windowScreen Recording
app_visibilityHide, unhide, or quit an applicationAccessibility
file_openOpen a file or folder, optionally in a given appNone
run_shortcutList or run Apple ShortcutsNone

Self-Correcting Menus

When Claude tries to click a menu item that doesn't exist, the server automatically returns the list of available items at that level — so Claude can retry with the correct name. No other MCP server does this.

User:   "Click File → Export as PDF in Preview"Claude: calls app_menu click ["File", "Export as PDF"]Server: "Menu item 'Export as PDF' not found in 'File'.         Available: ['New from Clipboard', 'Open...', 'Close', 'Save',         'Duplicate', 'Rename...', 'Export...', 'Export as PDF...']"Claude: calls app_menu click ["File", "Export as PDF..."]Server: "Clicked: File > Export as PDF..."

Why mcp-osascript?

mcp-osascriptsteipete (880★)peakmojo (464★)
Typed tools with validation182 (generic)1 (generic)
URL scheme allowlisthttp/https/mailtoNoNo
Env isolation (child process)PATH+HOME+LANG onlyFull process.envFull process.env
Process group kill (no orphans)SIGTERM→SIGKILLNoNo
Error sanitization (paths, tokens)YesNoNo
Prototype pollution protectionObject.create(null)NoNo
Self-correcting menu clickYesNoNo
Integration tests8400
Runs tests in CIYesNoNo
Red-team audit passes400
Untrusted-output fencingYesNoNo
Stdin piping (no temp files)YesTemp filesTemp files

Star counts are a popularity measure, not a quality one — both alternatives predate this project by months. The rows above are the things that differ in practice.

Security audits

Four red-team audit passes (adversarial agents run against the source, commissioned by the author — not a third-party certification), the most recent against v1.1.2 with three parallel agents covering the shell surface, AppleScript escaping, and information disclosure. It found six real defects, including a tool that silently annulled another tool's scheme allowlist and a concurrency slot that could leak until the server deadlocked. Every finding is fixed and carries a regression test. escapeAS was verified against 13 string-breakout candidates through real osascript — none escape.

Permissions

Tools work in three tiers:

  • No permission needed — clipboard, notifications, URLs, apps, files, displays, Shortcuts. Works immediately.
  • Automation — browser tabs, frontmost app. macOS prompts once per browser.
  • Accessibility — keyboard, windows, menus, hide/unhide. Grant once in System Settings → Privacy & Security → Accessibility.
  • Screen Recording — screenshots only. Grant in System Settings → Privacy & Security → Screen Recording.

Ask Claude to run check_permissions and it will tell you which of these are already granted, which tools each one unlocks, and exactly which settings pane to open for the rest. The probes are read-only and never trigger a permission prompt.

When a permission is missing, the server tells you exactly what to do:

"Accessibility permission required. Grant access to 'osascript'in System Settings > Privacy & Security > Accessibility."

Testing

bash
npm test

84 integration tests covering all 18 tools — input validation, security boundaries (URL scheme blocking, prototype pollution, script size limits), timeout enforcement, permission error handling, and regressions for every finding of the security audit.

Security & Architecture

Security

  • run_osascript executes arbitrary code — this is by design. The MCP client (Claude) is the trust boundary.
  • Scripts piped via stdin to /usr/bin/osascript — no temp files, no TOCTOU race conditions.
  • Script size: 50 KB max. Output: 50K chars max, truncated on a UTF-8 character boundary (no mojibake in non-Latin output).
  • Error messages sanitized — filesystem paths, tokens, and passwords are stripped.
  • Child processes get minimal env: PATH, HOME, LANG only — no API keys or secrets leak.
  • URL scheme allowlist — file://, smb://, vnc://, javascript: all blocked.
  • Handler dispatch uses Object.create(null) — no prototype pollution.
  • Externally-sourced text (browser tab titles, window titles, menu items, clipboard) is returned inside an explicit <untrusted-data> envelope, so a web page that renames itself cannot smuggle instructions into the model's context.
  • file_open refuses anything that parses as a URL — open(1) resolves URLs as well as paths, so without that check it would quietly annul open_url's scheme allowlist.
  • screenshot never overwrites an existing file unless overwrite: true, and the extension must match the format.
  • Every list-building tool strips |, CR and LF from app-supplied names, so a crafted window or tab title cannot forge a record.

Reliability

  • Process group kill on timeout — SIGTERM → 2s grace → SIGKILL. No orphaned processes.
  • Concurrency semaphore — max 5 simultaneous osascript processes.
  • Graceful shutdown — server.close() with 10s force-exit safety net.
  • Error classification — parses macOS error codes (-1728, -1743, -25211) into actionable messages. Supports English and Russian locales.

Requirements

  • macOS 13+ (Ventura or later)
  • Node.js 18+

License

MIT

来源：README.md，提交 8eb0731

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v1.1.3最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分