applescript-mcp

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

• AppleScript Language Guide
• MCP Protocol Documentation
• Issue Tracker

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - see LICENSE for details