Applescript MCP

applexcript mcp mcp服务器

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

](https://github.com/joshrutkowski/applescript-mcp/actions/workflows/node.js.yml)

特性

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

计划的功能

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

先决条件

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

可用类别

日历

例子

// 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?

剪贴板

例子

// 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 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 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

系统

例子

// 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 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

捷径

例子

// 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 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 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 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 "
Quarterly Report

Sales increased by 15%
"

// 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 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. AppleScript框架 (framework.ts)：主服务器类：

- 管理MCP协议通信 - 处理工具注册和执行 - 提供日志记录功能 - 执行AppleScript命令

1. 分类 (src/categories/*.ts)：按功能组织的模块化脚本集合：

- 每个类别都包含相关的脚本（例如日历、系统、注释） - 类别在框架中注册 index.ts

1. 类型 (src/types/index.ts)：TypeScript接口定义：

- ScriptDefinition：单个脚本的结构 - ScriptCategory：相关脚本集合 - LogLevel：标准记录级别 - FrameworkOptions：配置选项

执行流程

1. 客户端通过MCP协议发送工具请求
2. 服务器标识适当的类别和脚本
3. 生成脚本内容（静态或通过函数动态）
4. AppleScript通过macOS执行 osascript 命令
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;
   }

1. 处理复杂数据:

   // 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, '
$1
');
       // ...
     }
     
     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流是否未被重定向
• 数据库访问：某些功能（如消息）需要完全磁盘访问权限

资源

• AppleScript语言指南
• MCP协议文件
• 问题追踪

贡献

1. 分叉存储库
2. 创建要素分支
3. 提交您的更改
4. 推到分支
5. 创建拉取请求

许可证

MIT许可证-请参阅 许可证 详见