使用说明

applexcript 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`	从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构建的，遵循模块化架构：

核心组件

AppleScript框架 (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检查器提供了一个用于测试和调试服务器的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许可证-请参阅许可证详见