Skip to main content
Glama
deenesjakoruzh

macOS Automator MCP Server

by steipete
OverviewInspectSchemaRelated ServersScoreDiscussions
TypeScript
Local
MIT License
47
498

macOS Automator MCP 服务器

macOS Automator MCP 服务器

概述

该项目提供了一个模型上下文协议 (MCP) 服务器macos_automator ，允许在 macOS 上执行 AppleScript 和 JavaScript for Automation (JXA) 脚本。它具有一个预定义脚本知识库，可通过 ID 访问，并支持内联脚本、脚本文件和参数传递。该知识库在首次使用时会延迟加载，以加快服务器启动速度。

Related MCP server: AppleScript MCP Server

好处

  • 通过 MCP 远程执行 AppleScript/JXA 脚本。

  • 利用丰富、可扩展的常见 macOS 自动化任务知识库。

  • 以编程方式控制 macOS 应用程序和系统功能。

  • 将 macOS 自动化集成到更大的 AI 驱动的工作流程中。

先决条件

  • Node.js（建议版本 >=18.0.0，请参阅package.json引擎）。

  • macOS。

  • 关键权限设置：

    • 运行此 MCP 服务器的应用程序（例如，终端、您的 Node.js 应用程序）需要在运行该服务器的 macOS 计算机上获得明确的用户权限。

    • **自动化权限：**控制其他应用程序（Finder、Safari、Mail 等）。

      • 前往：系统设置>隐私和安全>自动化。

      • 在列表中找到运行服务器的应用程序（例如终端）。

      • 确保它需要控制的所有应用程序的复选框都已勾选。

      • 查看示例： docs/automation-permissions-example.png （占位符图像）。

    • **可访问性权限：**通过“系统事件”进行 UI 脚本编写（例如，模拟点击、击键）。

      • 前往：系统设置 > 隐私和安全 > 辅助功能。

      • 将运行服务器的应用程序（例如终端）添加到列表中并确保勾选其复选框。

    • 即使已预先授权，首次尝试控制新应用程序或使用辅助功能仍可能触发 macOS 确认提示。服务器本身无法授予这些权限。

安装和使用

运行此服务器的主要方式是通过npx 。这可确保您使用的是最新版本，而无需全局安装。

将以下配置添加到您的 MCP 客户端的mcp.json （或等效配置）：

{ "mcpServers": { "macos_automator": { "command": "npx", "args": [ "-y", "@steipete/macos-automator-mcp@latest" ] } } }

本地运行（用于开发或直接使用）

或者，如果您希望开发或直接从克隆的仓库运行服务器，则可以使用提供的start.sh脚本。如果您想进行本地修改或运行特定版本，这非常有用。

  1. 克隆存储库：

    git clone https://github.com/steipete/macos-automator-mcp.git cd macos-automator-mcp npm install # Ensure dependencies are installed

  2. **配置您的 MCP 客户端：**更新您的 MCP 客户端的配置以指向克隆存储库中的start.sh脚本的绝对路径。

    mcp.json配置片段示例：

    { "mcpServers": { "macos_automator_local": { "command": "/absolute/path/to/your/cloned/macos-automator-mcp/start.sh", "env": { "LOG_LEVEL": "DEBUG" } } } }

    **重要提示：**将/absolute/path/to/your/cloned/macos-automator-mcp/start.sh替换为系统上正确的绝对路径。

    如果未找到编译版本， start.sh脚本将自动使用tsx直接运行 TypeScript 源代码；如果dist/目录下有编译版本，则运行该版本。它遵循LOG_LEVEL环境变量。

    开发者须知： start.sh脚本旨在确保您始终通过 tsx 从src/运行最新的 TypeScript 代码，尤其是在修改为在执行前删除所有已编译的dist/server.js文件（例如，添加rm -f dist/server.js ）的tsx 。这对于开发环境非常理想，可以防止构建过时导致的问题。对于生产部署（例如，发布到 npm 时），构建过程通常会创建一个最终的dist/server.js文件，并将其作为已发布包的入口点。

提供的工具

1. execute_script

在 macOS 上执行 AppleScript 或 JavaScript for Automation (JXA) 脚本。脚本可以作为内联内容 ( script_content )、绝对文件路径 ( script_path ) 提供，也可以通过使用其唯一的kb_script_id引用内置知识库中的脚本来提供。

脚本来源（互斥）：

  • script_content （字符串）：原始脚本代码。

  • script_path (字符串)：脚本文件的绝对 POSIX 路径（例如， .applescript 、 .scpt 、 .js ）。

  • kb_script_id （字符串）：服务器知识库中预定义脚本的 ID。使用get_scripting_tips工具可以发现可用的脚本 ID 及其功能。

语言规范：

  • language （枚举：'applescript' | 'javascript'，可选）：指定语言。

    • 如果使用kb_script_id ，则从知识库脚本推断出语言。

    • 如果使用script_content或script_path并且省略language ，则默认为“applescript”。

将输入传递给脚本：

  • arguments （字符串数组，可选）：

    • 对于script_path ：作为标准参数传递给脚本的on run argv （AppleScript）或run(argv) （JXA）处理程序。

    • 对于kb_script_id ：如果预定义脚本被设计为接受位置字符串参数（例如，替换--MCP_ARG_1 、 --MCP_ARG_2等占位符），则使用 kb_script_id 。请从get_scripting_tips检查脚本的argumentsPrompt 。

  • input_data （JSON对象，可选）：

    • 主要用于接受命名、结构化输入的kb_script_id脚本。

    • 此对象的值将替换脚本中的占位符（例如， --MCP_INPUT:yourKeyName ）。请参阅get_scripting_tips中的argumentsPrompt 。

    • 值（字符串、数字、布尔值、简单数组/对象）将转换为其 AppleScript 文字等价物。

其他选项：

  • timeout_seconds （整数，可选，默认值：60）：最大执行时间。

  • output_format_mode （枚举，可选，默认值：'auto'）：控制osascript输出格式标志。

    • 'auto' ：（默认）对 AppleScript（ -sh ）使用人类可读的格式，对 JXA 使用直接输出（无-s标志）。

    • 'human_readable' ：强制-sh （人类可读的输出，主要用于 AppleScript）。

    • 'structured_error' ：强制-ss （结构化错误报告，主要用于 AppleScript）。

    • 'structured_output_and_error' ：强制-s ss （主要结果和错误的结构化输出，主要用于 AppleScript）。

    • 'direct' ：不使用-s标志（推荐用于 JXA，也是auto模式下 JXA 的行为）。

  • include_executed_script_in_output （布尔值，可选，默认值：false）：如果为 true，则输出将包含完整的脚本内容（在知识库脚本的任何占位符替换之后）或已执行的脚本路径。这将作为附加文本部分附加到输出内容数组中。

  • include_substitution_logs （布尔值，可选，默认值：false）：如果为 true，则在输出中包含对知识库脚本执行的占位符替换的详细日志。这对于调试如何处理input_data和arguments并将其插入脚本非常有用。如果成功，日志将添加到脚本输出的前面；如果失败，日志将附加到错误消息中。

  • report_execution_time （布尔值，可选，默认值：false）：如果为true ，则响应内容数组中将包含带有格式化脚本执行时间的附加消息。

**安全警告和 MACOS 权限：（**关于任意脚本执行和 macOS 自动化/辅助功能权限的严重警告与之前相同）。

例子：

  • （内联/文件路径的现有示例仍然相关）

  • 通过 ID 使用知识库脚本：

    { "toolName": "execute_script", "input": { "kb_script_id": "safari_get_active_tab_url", "timeout_seconds": 10 } }

  • 通过 ID 和

    { "toolName": "execute_script", "input": { "kb_script_id": "finder_create_folder_at_path", "input_data": { "folder_name": "New MCP Folder", "parent_path": "~/Desktop" } } }

响应格式：

execute_script工具返回以下格式的响应：

{ content: Array<{ type: 'text'; text: string; }>; isError?: boolean; }

  • content ：包含脚本输出的文本内容项数组

  • isError ：（布尔值，可选）当脚本执行发生错误时设置为true 。以下情况下会设置此标志：

    • 脚本输出（stdout）以“Error”开头（不区分大小写）

    • 这有助于客户端轻松确定执行是否失败，而无需解析输出文本

响应示例（成功）：

{ "content": [{ "type": "text", "text": "Script executed successfully" }] }

响应示例（错误）：

{ "content": [{ "type": "text", "text": "Error: Cannot find application 'Safari'" }], "isError": true }

2. get_scripting_tips

从服务器知识库检索 AppleScript/JXA 技巧、示例和可运行脚本的详细信息。有助于发现可用的脚本、它们的功能以及如何将它们与execute_script （尤其是kb_script_id ）一起使用。

参数：

  • list_categories （布尔值，可选，默认值：false）：如果为 true，则仅返回可用的知识库类别列表及其描述。覆盖其他参数。

  • category （字符串，可选）：按特定类别 ID 过滤提示（例如“finder”、“safari”）。

  • search_term （字符串，可选）：在提示标题、描述、脚本内容、关键字或 ID 中搜索关键字。

  • refresh_database （布尔值，可选，默认值：false）：如果为 true，则在处理请求之前强制从磁盘重新加载整个知识库。如果您正在开发过程中主动修改知识库文件，并且希望确保在不重启服务器的情况下使用最新版本，则此功能非常有用。

  • limit （整数，可选，默认值：10）：返回的最大结果数。

输出：

  • 返回包含所请求提示的 Markdown 格式的字符串，包括其标题、描述、脚本内容、语言、可运行 ID（如果适用）、参数提示和注释。

示例用法：

  • 列出所有类别： { "toolName": "get_scripting_tips", "input": { "list_categories": true } }

  • 获取“safari”类别的提示： { "toolName": "get_scripting_tips", "input": { "category": "safari" } }

  • 搜索与“clipboard”相关的提示： { "toolName": "get_scripting_tips", "input": { "search_term": "clipboard" } }

关键用例和示例

  • 应用程序控制：

    • 从 Safari 获取当前 URL： { "input": { "script_content": "tell application \"Safari\" to get URL of front document" } }

    • 获取邮件中未读邮件的主题： { "input": { "script_content": "tell application \"Mail\" to get subject of messages of inbox whose read status is false" } }

  • 文件系统操作：

    • 列出桌面上的文件： { "input": { "script_content": "tell application \"Finder\" to get name of every item of desktop" } }

    • 创建一个新文件夹： { "input": { "script_content": "tell application \"Finder\" to make new folder at desktop with properties {name:\"My New Folder\"}" } }

  • 系统交互：

    • 显示系统通知： { "input": { "script_content": "display notification \"Important Update!\" with title \"System Alert\"" } }

    • 设置系统音量： { "input": { "script_content": "set volume output volume 50" } } （0-100）

    • 获取当前剪贴板内容： { "input": { "script_content": "the clipboard" } }

故障排除

  • **权限错误：**如果脚本无法控制应用程序或执行 UI 操作，请在系统设置中仔细检查运行 MCP 服务器的应用程序（例如终端）的自动化和辅助功能权限。

  • 脚本语法错误： osascript错误将返回到stderr或错误消息中。请先使用脚本编辑器（适用于 AppleScript）或 JXA 运行器在本地测试复杂的脚本。

  • **超时：**如果脚本运行时间超过timeout_seconds （默认 60 秒），它将被终止。对于长时间运行的脚本，请增加超时时间。

  • **未找到文件：**确保script_path是运行 MCP 服务器的用户可以访问的绝对 POSIX 路径。

  • **输出/JXA 错误问题：**对于 JXA 脚本，尤其是使用 Objective-C 桥接的脚本，请确保将output_format_mode设置为'direct'或'auto' （默认）。在 JXA 中使用 AppleScript 特定的格式化标志（例如human_readable可能会导致错误。如果 AppleScript 输出解析不正确，请尝试使用structured_output_and_error或structured_error 。

通过环境变量配置

  • LOG_LEVEL ：设置服务器的日志记录级别。

    • 值： DEBUG 、 INFO 、 WARN 、 ERROR

    • 例如： LOG_LEVEL=DEBUG npx @steipete/macos-automator-mcp@latest

  • KB_PARSING ：控制何时解析知识库（脚本提示）。

    • 值：

      • lazy （默认）：在第一次请求get_scripting_tips时或在execute_script中使用kb_script_id时解析知识库。这可以加快服务器启动速度。

      • eager ：服务器启动时会解析知识库。这可能会稍微增加启动时间，但可以确保知识库立即可用，并尽早发现任何解析错误。

    • 示例（通过start.sh或类似程序运行时）：

      KB_PARSING=eager ./start.sh

    • 示例（通过支持env的 MCP 运行器进行配置时，例如mcp-agentify ）：

      { "env": { "LOG_LEVEL": "INFO", "KB_PARSING": "eager" } }

对于开发人员

有关本地开发、项目结构（包括knowledge_base ）和贡献指南的详细说明，请参阅DEVELOPMENT.md 。

发展

有关项目结构、构建和测试的详细信息，请参阅DEVELOPMENT.md 。

本地知识库

您可以使用自己的本地提示和共享处理程序来补充内置知识库。请在此存储库（或其子集）中创建与knowledge_base相同的目录结构。

默认情况下，应用程序会在~/.macos-automator/knowledge_base中查找本地知识库。您可以通过设置LOCAL_KB_PATH环境变量来自定义此路径。

例子：

假设你的本地知识库位于/Users/yourname/my-custom-kb 。设置环境变量： export LOCAL_KB_PATH=/Users/yourname/my-custom-kb

或者，如果您正在运行验证器脚本，则可以使用--local-kb-path参数： npm run validate:kb -- --local-kb-path /Users/yourname/my-custom-kb

结构和覆盖：

  • 您的本地知识库应该反映主knowledge_base的类别结构（例如， 01_applescript_core ， 05_web_browsers/safari等）。

  • 您可以添加新的.md提示文件或_shared_handlers （例如.applescript或.js文件）。

  • 如果您本地知识库中的提示 ID（来自 frontmatter id:或从文件名/路径生成）与嵌入式知识库中的 ID 匹配，则您的本地版本将覆盖嵌入式版本。

  • 类似地，本地_shared_handlers目录中具有相同名称和语言的共享处理程序（例如， my_utility.applescript ）将覆盖同一类别中具有相同名称和语言的任何嵌入处理程序（或者，如果将它们放在本地 KB 的_shared_handlers的根目录中，则为全局）。

  • 本地 KB 中的_category_info.md的类别描述也可以覆盖同一类别的嵌入 KB 中的类别描述。

这允许个性化和扩展可用的自动化脚本和提示，而无需修改核心应用程序文件。

贡献

欢迎贡献！请将问题和拉取请求提交到GitHub 仓库。

自动化功能

该服务器通过 AppleScript 和 JavaScript for Automation (JXA) 提供强大的 macOS 自动化功能。以下是一些最实用的示例：

码头自动化

  • 在新的终端选项卡中运行命令：

    { "input": { "kb_script_id": "terminal_app_run_command_new_tab", "input_data": { "command": "ls -la" } } }

  • 使用 sudo 执行命令并安全地提供密码

  • 捕获命令输出以进行处理

浏览器控制

  • Chrome/Safari 自动化：

    { "input": { "kb_script_id": "chrome_open_url_new_tab_profile", "input_data": { "url": "https://example.com", "profile_name": "Default" } } }
    { "input": { "kb_script_id": "safari_get_front_tab_url" } }

  • 在浏览器上下文中执行 JavaScript：

    { "input": { "kb_script_id": "chrome_execute_javascript", "input_data": { "javascript_code": "document.title" } } }

  • 提取页面内容、操作表单并自动化工作流程

  • 截取网页截图

系统交互

  • 切换系统设置（暗模式、音量、网络）：

    { "input": { "kb_script_id": "systemsettings_toggle_dark_mode_ui" } }

  • 获取/设置剪贴板内容：

    { "input": { "kb_script_id": "system_clipboard_get_file_paths" } }

  • 打开/控制系统对话框和警报

  • 创建和管理系统通知

文件操作

  • 创建、移动和操作文件/文件夹：

    { "input": { "kb_script_id": "finder_create_new_folder_desktop", "input_data": { "folder_name": "My Project" } } }

  • 读写文本文件：

    { "input": { "kb_script_id": "fileops_read_text_file", "input_data": { "file_path": "~/Documents/notes.txt" } } }

  • 列出并过滤目录中的文件

  • 获取文件元数据和属性

应用程序集成

  • 日历/提醒管理：

    { "input": { "kb_script_id": "calendar_create_event", "input_data": { "title": "Meeting", "start_date": "2023-06-01 10:00", "end_date": "2023-06-01 11:00" } } }

  • 使用 Mail.app 实现电子邮件自动化：

    { "input": { "kb_script_id": "mail_send_email_direct", "input_data": { "recipient": "user@example.com", "subject": "Hello", "body_content": "Message content" } } }

  • 控制音乐播放：

    { "input": { "kb_script_id": "music_playback_controls", "input_data": { "action": "play" } } }

  • 使用创意应用程序（Keynote、Pages、Numbers）

使用get_scripting_tips工具探索按类别组织的所有可用自动化功能。

执照

本项目遵循 MIT 许可证。详情请参阅LICENSE文件。

One-click Deploy
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/steipete/macos-automator-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server