苹果脚本-mcp

Name: 苹果脚本-mcp
Author: joshrutkowski

作者：joshrutkowski324 星标更新：2025-04-20

安装使用来源：spider==github.com

项目介绍

applescript-mcp MCP 服务器

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

功能

🗓️ 日历管理（事件、提醒）
📋 剪贴板操作
🔍 寻找器集成
🔔 系统通知
⚙️ 系统控制（音量、暗模式、应用）
📟 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构建，并遵循模块化架构：

核心组件

AppleScript框架（framework.ts）：主要服务器类，负责：
- 管理MCP协议通信
- 处理工具注册和执行
- 提供日志记录功能
- 执行AppleScript命令
类别（src/categories/*.ts）：按功能组织的模块化脚本集合：
- 每个类别包含相关的脚本（例如，日历、系统、笔记）
- 类别在index.ts中注册
类型（src/types/index.ts）：定义TypeScript接口：
- ScriptDefinition：单个脚本的结构
- ScriptCategory：相关脚本的集合
- LogLevel：标准日志级别
- FrameworkOptions：配置选项

执行流程

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

日志系统

框架包括一个全面的日志系统，支持：

同时向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);

高级脚本开发

对于更复杂的脚本，可以：

使用动态脚本生成：

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

处理复杂数据：

// 示例来自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流是否被重定向
数据库访问：某些功能（如消息）需要完整的磁盘访问权限

资源

贡献

分叉仓库
创建功能分支
提交更改
推送到分支
创建拉取请求

许可证

MIT许可证 - 详情见LICENSE