applescript-mcp MCP Server

A Model Context Protocol server that enables LLM applications to interact with macOS through AppleScript. This server provides a standardized interface for AI applications to control system functions, manage files, handle notifications, and more.

Features

🗓️ Calendar management (events, reminders)
📋 Clipboard operations
🔍 Finder integration
🔔 System notifications
⚙️ System controls (volume, dark mode, apps)
📟 iTerm terminal integration

Planned Features

📬 Mail (list emails, save attachments, summarize, send)
🧭 Safari (open in Safari, save page content, get selected page/tab)
💬 Messages (send, get, list)
✅ Reminders (create, get)
🗒️ Notes (create, get, list)

Prerequisites

macOS 10.15 or later
Node.js 18 or later

Available Categories

Calendar

Command	Description	Parameters
`add`	Create calendar event	`title`, `startDate`, `endDate`
`list`	List today's events	None

Clipboard

Command	Description	Parameters
`set_clipboard`	Copy to clipboard	`content`
`get_clipboard`	Get clipboard contents	None
`clear_clipboard`	Clear clipboard	None

Finder

Command	Description	Parameters
`get_selected_files`	Get selected files	None
`search_files`	Search for files	`query`, `location` (optional)
`quick_look`	Preview file	`path`

Notifications

Command	Description	Parameters
`send_notification`	Show notification	`title`, `message`, `sound` (optional)
`toggle_do_not_disturb`	Toggle DND mode	None

System

Command	Description	Parameters
`volume`	Set system volume	`level` (0-100)
`get_frontmost_app`	Get active app	None
`launch_app`	Open application	`name`
`quit_app`	Close application	`name`, `force` (optional)
`toggle_dark_mode`	Toggle dark mode	None

iTerm

Command	Description	Parameters
`paste_clipboard`	Paste to iTerm	None
`run`	Execute command	`command`, `newWindow` (optional)

Development

Setup

# 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...

Adding New Functionality

1. Create Category File

Create 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. Add Scripts

{
  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. Register Category

Update src/index.ts:

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

Debugging

Using MCP Inspector

The MCP Inspector provides a web interface for testing and debugging your server:

npm run inspector

Logging

Enable debug logging by setting the environment variable:

DEBUG=applescript-mcp* npm start

Common Issues

Permission Errors: Check System Preferences > Security & Privacy
Script Failures: Test scripts directly in Script Editor.app
Communication Issues: Check stdio streams aren't being redirected

Resources

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

MIT License - see LICENSE for details