applescript-mcp MCP Server

applescript-mcp MCP 服务

一个模型上下文协议服务，可通过 AppleScript 让大模型应用与 macOS 交互。 此服务提供标准化接口，供 AI 应用控制系统功能、管理文件、处理通知等。

功能

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

计划中的功能

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

前置条件

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

可用类别

日历

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

示例

// Create a new calendar event
Create a calendar event titled "Team Meeting" starting tomorrow at 2pm for 1 hour

// List today's events
What events do I have scheduled for today?

剪贴板

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

示例

// Copy text to clipboard
Copy "Remember to buy groceries" to my clipboard

// Get clipboard contents
What's currently in my clipboard?

// Clear clipboard
Clear my clipboard

Finder

命令	描述	参数
get_selected_files	获取选中的文件	无
search_files	搜索文件	query、location（可选）
quick_look	预览文件	path

示例

// Get selected files in Finder
What files do I currently have selected in Finder?

// Search for files
Find all PDF files in my Documents folder

// Preview a file
Show me a preview of ~/Documents/report.pdf

通知

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

命令	描述	参数
send_notification	显示通知	title、message、sound（可选）
toggle_do_not_disturb	切换勿扰模式	无

示例

// Send a notification
Send me a notification with the title "Reminder" and message "Time to take a break"

// Toggle Do Not Disturb
Turn on Do Not Disturb mode

系统

命令	描述	参数
volume	设置系统音量	level（0-100）
get_frontmost_app	获取当前活动应用	无
launch_app	打开应用程序	name
quit_app	关闭应用程序	name、force（可选）
toggle_dark_mode	切换深色模式	无

示例

// Set system volume
Set my Mac's volume to 50%

// Get active application
What app am I currently using?

// Launch an application
Open Safari

// Quit an application
Close Spotify

// Toggle dark mode
Switch to dark mode

iTerm

命令	描述	参数
paste_clipboard	粘贴到 iTerm	无
run	执行命令	command、newWindow（可选）

示例

// Paste clipboard to iTerm
Paste my clipboard contents into iTerm

// Run a command in iTerm
Run "ls -la" in iTerm

// Run a command in a new iTerm window
Run "top" in a new iTerm window

快捷指令

命令	描述	参数
run_shortcut	运行快捷指令	name、input（可选）
list_shortcuts	列出所有可用的快捷指令	limit（可选）

示例

// List available shortcuts
List all my available shortcuts

// List with limit
Show me my top 5 shortcuts

// Run a shortcut
Run my "Daily Note in Bear" shortcut

// Run a shortcut with input
Run my "Add to-do" shortcut with input "Buy groceries"

邮件

命令	描述	参数
create_email	在 Mail.app 中创建新邮件	recipient、subject、body
list_emails	列出邮箱中的邮件	mailbox（可选）、count（可选）、unreadOnly（可选）
get_email	根据搜索条件获取特定邮件	subject（可选）、sender（可选）、dateReceived（可选）、mailbox（可选）、account（可选）、unreadOnly（可选）、includeBody（可选）

示例

// Create a new email
Compose an email to [email protected] with subject "Meeting Tomorrow" and body "Hi John, Can we meet tomorrow at 2pm?"

// List emails
Show me my 10 most recent unread emails

// Get a specific email
Find the email from [email protected] about "Project Update"

信息

命令	描述	参数
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）

示例

// List available chats
Show me my recent message conversations

// Get recent messages
Show me my last 20 messages

// Search messages
Find messages containing "dinner plans" from John in the last week

// Compose a message
Send a message to 555-123-4567 saying "I'll be there in 10 minutes"

备忘录

命令	描述	参数
create	创建支持类似 Markdown 格式的备忘录	title、content、format（可选，包含格式选项）
createRawHtml	直接使用 HTML 内容创建备忘录	title、html
list	列出备忘录，也可指定文件夹	folder（可选）
get	根据标题获取特定备忘录	title、folder（可选）
search	搜索包含特定文本的备忘录	query、folder（可选）、limit（可选，默认值：5）、includeBody（可选，默认值：true）

示例

// Create a new note with markdown formatting
Create a note titled "Meeting Minutes" with content "# Discussion Points\n- Project timeline\n- Budget review\n- Next steps" and format headings and lists

// Create a note with HTML
Create a note titled "Formatted Report" with HTML content "<h1>Quarterly Report</h1><p>Sales increased by <strong>15%</strong></p>"

// List notes
Show me all my notes in the "Work" folder

// Get a specific note
Show me my note titled "Shopping List"

// Search notes
Find notes containing "recipe" in my "Cooking" folder

Pages

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

示例

// Create a new Pages document
Create a Pages document with the content "Project Proposal\n\nThis document outlines the scope and timeline for the upcoming project."

架构

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

核心组件

1. AppleScriptFramework（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 日志协议
• 支持多个严重级别（调试、信息、警告、错误等）
• 提供详细的执行信息以便排查问题

开发

设置

# Install dependencies
npm install

# Build the server
npm run build

# Launch MCP Inspector
# See: 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: [
    // Scripts will go here
  ],
};

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"
      // AppleScript code using ${args.paramName}
    end tell
  `
}

3. 注册分类

更新 src/index.ts：

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

高级脚本开发

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

1. 使用动态脚本生成：

   script: (args) => {
     // Process arguments and build script dynamically
     let scriptContent = `tell application "App"\n`;
     
     if (args.condition) {
       scriptContent += `  // Conditional logic\n`;
     }
     
     scriptContent += `end tell`;
     return scriptContent;
   }
   

2. 处理复杂数据：

   // Example from Notes category
   function generateNoteHtml(args: any): string {
     // Process markdown-like syntax into 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 中直接测试脚本
• 通信问题：检查是否有标准输入输出流被重定向
• 数据库访问：某些功能（例如 Messages）需要“完全磁盘访问”权限

资源

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

贡献

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

许可证

MIT 许可证——详情请参阅 LICENSE