applescript-mcp MCP 服务器

一个模型上下文协议服务器，使LLM应用程序能够通过AppleScript与macOS进行交互。 该服务器为AI应用程序提供了一个标准化接口，用于控制系统功能、管理文件、处理通知等。

<a href="https://glama.ai/mcp/servers/0t5gydjcqw"><img width="380" height="200" src="https://gips2.baidu.com/it/u=2974277007,2893364160&fm=3081&app=3081&f=PNG?w=760&h=400" alt="applescript-mcp MCP 服务器" /></a>

功能

• 🗓️ 日历管理（事件、提醒）
• 📋 剪贴板操作
• 🔍 寻找器集成
• 🔔 系统通知
• ⚙️ 系统控制（音量、暗模式、应用）
• 📟 iTerm 终端集成
• 📬 邮件（创建新邮件、列出邮件、获取邮件）
• 🔄 快捷方式自动化
• 💬 消息（列出聊天、获取消息、搜索消息、发送消息）
• 🗒️ 笔记（创建格式化笔记、列出笔记、搜索笔记）
• 📄 页面（创建文档）

计划功能

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

先决条件

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

可用类别

日历

命令	描述	参数
add	创建日历事件	title，startDate，endDate，calendar（可选）
list	列出今天的事件	无

示例

// 创建新的日历事件
创建一个名为“团队会议”的日历事件，从明天下午2点开始，持续1小时

// 列出今天的事件
今天我有哪些计划？

剪贴板

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

示例

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

// 获取剪贴板内容
目前我的剪贴板里有什么？

// 清空剪贴板
清空我的剪贴板

寻找器

命令	描述	参数
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写一封主题为“明天会议”的邮件，正文为“John，我们明天下午2点能见面吗？”

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

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

消息

命令	描述	参数
list_chats	列出可用的iMessage和SMS聊天	includeParticipantDetails（可选，默认为false）
get_messages	获取Messages应用中的消息	limit（可选，默认为100）
search_messages	搜索包含特定文本的消息	searchText，sender（可选），chatId（可选），limit（可选，默认为50），daysBack（可选，默认为30）
compose_message	打开Messages应用并预填消息或自动发送	recipient（必需），body（可选），auto（可选，默认为false）

示例

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

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

// 搜索消息
查找过去一周内John发送的包含“晚餐计划”的消息

// 编写消息
给555-123-4567发送一条消息：“我10分钟后到”

笔记

命令	描述	参数
create	创建带有类似Markdown格式的笔记	title，content，format（可选，带格式选项）
createRawHtml	使用直接HTML内容创建笔记	title，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>"

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

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

// 搜索笔记
查找包含“食谱”的笔记，在我的“烹饪”文件夹中

页面

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

示例

// 创建新的Pages文档
创建一个Pages文档，内容为"项目提案\n\n此文档概述了即将开展项目的范围和时间表。"

架构

applescript-mcp服务器使用TypeScript构建，并遵循模块化架构：

核心组件

1. AppleScript框架（framework.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 Inspector
# 查看：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: "类别描述",
  scripts: [
    // 脚本将放在这里
  ],
};

2. 添加脚本

{
  name: "script_name",
  description: "脚本的作用",
  schema: {
    type: "object",
    properties: {
      paramName: {
        type: "string",
        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 Inspector

MCP Inspector提供了测试和调试服务器的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流是否被重定向
• 数据库访问：某些功能（如消息）需要完整的磁盘访问权限

资源

• AppleScript语言指南
• MCP协议文档
• 问题跟踪器

贡献

1. 分叉仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建拉取请求

许可证

MIT许可证 - 详情见LICENSE