📌Overview

Purpose: To provide a Model Context Protocol server enabling LLM applications to interact with macOS functionalities through AppleScript.

Overview: The applescript-mcp MCP Server streamlines communication between AI applications and macOS, allowing for control over various system functions, file management, notifications, and more via a standardized interface.

Key Features:

Calendar Management: Facilitates event and reminder handling, enabling users to manage their schedules efficiently.
Clipboard Operations: Allows copying, retrieving, and clearing of clipboard contents, enhancing information management capabilities.
Finder Integration: Users can quickly access files through commands for searching and selecting, improving productivity.
System Notifications: Enables sending notifications and toggling Do Not Disturb mode, keeping users informed without interruptions.
System Controls: Provides commands to control system settings like volume and dark mode, offering seamless user experience customization.
iTerm Integration: Supports executing commands and pasting content in iTerm, making terminal operations more accessible.

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`
`quick_look`	Preview file	`path`

Notifications

Command	Description	Parameters
`send_notification`	Show notification	`title`, `message`, `sound`
`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`
`toggle_dark_mode`	Toggle dark mode	None

iTerm

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

Development

Setup

npm install
npm run build
npx @modelcontextprotocol/inspector node path/to/server/index.js args...

Adding New Functionality

Create Category File

import { ScriptCategory } from "../types/index.js";

export const newCategory: ScriptCategory = {
  name: "category_name",
  description: "Category description",
  scripts: []
};

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
  `
}

Register Category

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

Debugging

Using MCP Inspector

npm run inspector

Logging

Enable debug logging:

DEBUG=applescript-mcp* npm start

Common Issues

Permission Errors: Check System Preferences > Security & Privacy
Script Failures: Test scripts in Script Editor.app
Communication Issues: Check stdio streams aren't 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