applescript-mcp

applescript-mcp MCP 服务器

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

特征

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

计划功能

🧭 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

发现者

命令	描述	参数
`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`	切换 DND 模式	没有任何

示例

// 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 john@example.com 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 sarah@example.com about "Project Update"

消息

命令	描述	参数
`list_chats`	列出可用的 iMessage 和 SMS 聊天	`includeParticipantDetails` （可选，默认值：false）
`get_messages`	从“信息”应用获取信息	`limit` （可选，默认值：100）
`search_messages`	搜索包含特定文本的消息	`searchText` 、 `sender` （可选）、 `chatId` （可选）、 `limit` （可选，默认值：50）、 `daysBack` （可选，默认值：30）
`compose_message`	打开“信息”应用，输入预填信息或自动发送	`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

页面

命令	描述	参数
`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 构建，并遵循模块化架构：

核心组件

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

执行流程

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

日志系统

该框架包括一个全面的日志系统：

记录到 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);

高级脚本开发

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

使用动态脚本生成：
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; }
处理复杂数据：
// 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 检查器

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 许可证 - 详情请参阅许可证

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

使 LLM 应用程序能够通过 AppleScript 与 macOS 交互。

Related MCP Servers

MCP-Server-Playwright
Automata-Labs-team
A
security
A
license
A
quality
Enables LLMs to interact with web pages, take screenshots, and execute JavaScript in a real browser environment
Last updated -
10
685
252
MIT License
MCP-AppleMusic
kennethreitz
A
security
A
license
A
quality
Facilitates controlling Apple Music on macOS via AppleScript through MCP commands, allowing users to manage playback, search for tracks, and create playlists.
Last updated -
10
52
MIT License
Lightning Tools MCP Server
getAlby
A
security
F
license
A
quality
Enables interaction with lightning addresses and common lightning tools via your LLM, providing Lightning Network functionality through natural language.
Last updated -
3
7
1
AppleScript MCP Server
peakmojo
A
security
A
license
A
quality
A Model Context Protocol server that enables running AppleScript code to interact with Mac applications and system features including Notes, Calendar, Contacts, Messages, file management, and more.
Last updated -
1
128
353
MIT License

View all related MCP servers