首页
学习
活动
专区
圈层
工具
发布
精选内容/技术社群/优惠产品,尽在小程序
立即前往
首页
学习
活动
专区
圈层
工具
MCP广场
MCP广场 >详情页
applescript-mcp2025-05-290分享
github
启用LLM应用程序通过AppleScript与macOS交互。
By joshrutkowski
2025-05-290
github
详情内容

applescript-mcp MCP服务器

这是一个模型上下文协议(MCP)服务器,使大型语言模型(LLM)应用能够通过AppleScript与macOS系统交互。
该服务器为AI应用提供了标准化接口,用于控制系统功能、管理文件、处理通知等操作。

Node.js CI

applescript-mcp MCP服务器

功能特性

  • 🗓️ 日历管理(事件、提醒事项)
  • 📋 剪贴板操作
  • 🔍 Finder集成
  • 🔔 系统通知
  • ⚙️ 系统控制(音量、暗黑模式、应用程序)
  • 📟 iTerm终端集成
  • 📬 邮件(创建新邮件、列出邮件、获取邮件)
  • 🔄 快捷指令自动化
  • 💬 信息(列出聊天、获取消息、搜索消息、发送消息)
  • 🗒️ 笔记(创建格式化笔记、列出笔记、搜索笔记)
  • 📄 Pages(创建文档)

规划中的功能

  • 🧭 Safari(在Safari中打开、保存页面内容、获取选中页面/标签)
  • ✅ 提醒事项(创建、获取)

前提条件

  • macOS 10.15或更高版本
  • Node.js 18或更高版本

可用分类

日历

命令 描述 参数
add 创建日历事件 title(标题), startDate(开始日期), endDate(结束日期), calendar(日历,可选)
list 列出今天的事件

示例

// 创建新的日历事件
创建一个标题为"团队会议"的日历事件,从明天下午2点开始,持续1小时

// 列出今天的事件
我今天安排了哪些事件?

剪贴板

命令 描述 参数
set_clipboard 复制到剪贴板 content(内容)
get_clipboard 获取剪贴板内容
clear_clipboard 清除剪贴板

示例

// 复制文本到剪贴板
将"记得买杂货"复制到我的剪贴板

// 获取剪贴板内容
我的剪贴板当前有什么内容?

// 清除剪贴板
清除我的剪贴板

Finder

命令 描述 参数
get_selected_files 获取选中的文件
search_files 搜索文件 query(查询), location(位置,可选)
quick_look 预览文件 path(路径)

示例

// 获取Finder中选中的文件
我目前在Finder中选中了哪些文件?

// 搜索文件
在我的文档文件夹中查找所有PDF文件

// 预览文件
显示~/Documents/report.pdf的预览

通知

注意:发送通知需要在系统设置 > 通知 > 脚本编辑器中启用通知。

命令 描述 参数
send_notification 显示通知 title(标题), message(消息), sound(声音,可选)
toggle_do_not_disturb 切换勿扰模式

示例

// 发送通知
给我发送一个标题为"提醒",内容为"该休息一下了"的通知

// 切换勿扰模式
开启勿扰模式

系统

命令 描述 参数
volume 设置系统音量 level(级别,0-100)
get_frontmost_app 获取当前活动应用
launch_app 打开应用程序 name(名称)
quit_app 关闭应用程序 name(名称), force(强制,可选)
toggle_dark_mode 切换暗黑模式

示例

// 设置系统音量
将我的Mac音量设置为50%

// 获取当前活动应用
我当前正在使用什么应用?

// 打开应用程序
打开Safari

// 关闭应用程序
关闭Spotify

// 切换暗黑模式
切换到暗黑模式

iTerm

命令 描述 参数
paste_clipboard 粘贴到iTerm
run 执行命令 command(命令), newWindow(新窗口,可选)

示例

// 将剪贴板内容粘贴到iTerm
将我的剪贴板内容粘贴到iTerm中

// 在iTerm中运行命令
在iTerm中运行"ls -la"

// 在新的iTerm窗口中运行命令
在新的iTerm窗口中运行"top"

快捷指令

命令 描述 参数
run_shortcut 运行快捷指令 name(名称), input(输入,可选)
list_shortcuts 列出所有可用快捷指令 limit(限制,可选)

示例

// 列出可用快捷指令
列出我所有可用的快捷指令

// 带限制地列出
显示我的前5个快捷指令

// 运行快捷指令
运行我的"每日Bear笔记"快捷指令

// 带输入运行快捷指令
运行我的"添加待办事项"快捷指令,输入为"买杂货"

邮件

命令 描述 参数
create_email 在Mail.app中创建新邮件 recipient(收件人), subject(主题), body(正文)
list_emails 列出邮箱中的邮件 mailbox(邮箱,可选), count(数量,可选), unreadOnly(仅未读,可选)
get_email 通过搜索获取特定邮件 subject(主题,可选), sender(发件人,可选), dateReceived(接收日期,可选), mailbox(邮箱,可选), account(账户,可选), unreadOnly(仅未读,可选), includeBody(包含正文,可选)

示例

// 创建新邮件
撰写一封发送给john@example.com的邮件,主题为"明天会议",正文为"Hi John,我们明天下午2点可以开会吗?"

// 列出邮件
显示我最近的10封未读邮件

// 获取特定邮件
查找来自sarah@example.com关于"项目更新"的邮件

信息

命令 描述 参数
list_chats 列出可用的iMessage和SMS聊天 includeParticipantDetails(包含参与者详情,可选,默认为false)
get_messages 获取信息应用中的消息 limit(限制,可选,默认为100)
search_messages 搜索包含特定文本的消息 searchText(搜索文本), sender(发件人,可选), chatId(聊天ID,可选), limit(限制,可选,默认为50), daysBack(回溯天数,可选,默认为30)
compose_message 打开信息应用并预填消息或自动发送 recipient(收件人,必填), body(正文,可选), auto(自动发送,可选,默认为false)

示例

// 列出可用聊天
显示我最近的信息对话

// 获取最近消息
显示我最后20条消息

// 搜索消息
查找John在过去一周内发送的包含"dinner plans"的消息

// 撰写消息
向555-123-4567发送消息:"我10分钟后到"

笔记

命令 描述 参数
create 创建带有类似markdown格式的笔记 title(标题), content(内容), format(格式,可选,带有格式化选项)
createRawHtml 创建带有直接HTML内容的笔记 title(标题), html(HTML)
list 列出笔记,可选来自特定文件夹 folder(文件夹,可选)
get 通过标题获取特定笔记 title(标题), folder(文件夹,可选)
search 搜索包含特定文本的笔记 query(查询), folder(文件夹,可选), limit(限制,可选,默认为5), includeBody(包含正文,可选,默认为true)

示例

// 创建带有markdown格式的新笔记
创建一个标题为"会议纪要"的笔记,内容为"# 讨论要点\n- 项目时间线\n- 预算审查\n- 下一步",并格式化标题和列表

// 创建带有HTML的笔记
创建一个标题为"格式化报告"的笔记,HTML内容为"<h1>季度报告</h1><p>销售额增长了<strong>15%</strong></p>"

// 列出笔记
显示我"工作"文件夹中的所有笔记

// 获取特定笔记
显示我标题为"购物清单"的笔记

// 搜索笔记
在我的"烹饪"文件夹中查找包含"recipe"的笔记

Pages

命令 描述 参数
create_document 使用纯文本创建新的Pages文档 content(内容)

示例

// 创建新的Pages文档
创建一个Pages文档,内容为"项目提案\n\n本文档概述了即将进行的项目的范围和时间线。"

架构

applescript-mcp服务器使用TypeScript构建,采用模块化架构:

核心组件

  1. AppleScriptFrameworkframework.ts):主服务器类,负责:

    • 管理MCP协议通信
    • 处理工具注册和执行
    • 提供日志功能
    • 执行AppleScript命令
  2. 分类src/categories/*.ts):按功能组织的模块化脚本集合:

    • 每个分类包含相关脚本(如日历、系统、笔记)
    • 分类在index.ts中注册到框架
  3. 类型src/types/index.ts):TypeScript接口定义:

    • ScriptDefinition:单个脚本的结构
    • ScriptCategory:相关脚本的集合
    • LogLevel:标准日志级别
    • FrameworkOptions:配置选项

执行流程

  1. 客户端通过MCP协议发送工具请求
  2. 服务器识别适当的分类和脚本
  3. 生成脚本内容(静态或通过函数动态生成)
  4. 通过macOS的osascript命令执行AppleScript
  5. 将结果返回给客户端

日志系统

框架包含一个全面的日志系统,可以:

  • 同时记录到stderr和MCP日志协议
  • 支持多种严重级别(调试、信息、警告、错误等)
  • 提供详细的执行信息用于故障排除

开发

设置

# 安装依赖
npm install

# 构建服务器
npm run build

# 启动MCP检查器
# 参见:https://modelcontextprotocol.io/docs/tools/inspector
npx @modelcontextprotocol/inspector node path/to/server/index.js args...

添加新功能

1. 创建分类文件

创建src/categories/newcategory.ts

import { ScriptCategory } from "../types/index.js";

export const newCategory: ScriptCategory = {
  name: "category_name",
  description: "Category description",
  scripts: [
    // 脚本将放在这里
  ],
};

2. 添加脚本

{
  name: "script_name",
  description: "What the script does",
  schema: {
    type: "object",
    properties: {
      paramName: {
        type: "string",
        description: "Parameter description"
      }
    },
    required: ["paramName"]
  },
  script: (args) => `
    tell application "App"
      // 使用${args.paramName}的AppleScript代码
    end tell
  `
}

3. 注册分类

更新src/index.ts

import { newCategory } from "./categories/newcategory.js";
// ...
server.addCategory(newCategory);

高级脚本开发

对于更复杂的脚本,你可以:

  1. 使用动态脚本生成

    script: (args) => {
      // 处理参数并动态构建脚本
      let scriptContent = `tell application "App"\n`;
      
      if (args.condition) {
        scriptContent += `  // 条件逻辑\n`;
      }
      
      scriptContent += `end tell`;
      return scriptContent;
    }
    
  2. 处理复杂数据

    // 来自Notes分类的示例
    function generateNoteHtml(args: any): string {
      // 将类似markdown的语法处理为HTML
      let processedContent = content;
      
      if (format.headings) {
        processedContent = processedContent.replace(/^# (.+)$/gm, '<h1>$1</h1>');
        // ...
      }
      
      return processedContent;
    }
    

调试

使用MCP检查器

MCP检查器提供了一个用于测试和调试服务器的Web界面:

npm run inspector

日志

通过设置环境变量启用调试日志:

DEBUG=applescript-mcp* npm start

示例配置

运行npm run build后,将以下内容添加到你的mcp.json文件中:

{
  "mcpServers": {
    "applescript-mcp-server": {
      "command": "node",
      "args": ["/path/to/applescript-mcp/dist/index.js"]
    }
  }
}

常见问题

  • 权限错误:检查系统偏好设置 > 安全性与隐私 > 隐私 > 自动化
  • 脚本失败:在集成之前,先直接在Script Editor.app中测试脚本
  • 通信问题:检查stdio流没有被重定向
  • 数据库访问:某些功能(如信息)需要"完全磁盘访问"权限

资源

贡献

  1. 分叉仓库
  2. 创建功能分支
  3. 提交你的更改
  4. 推送到分支
  5. 创建Pull Request

许可证

MIT许可证 - 详情见LICENSE文件

领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档