applescript-mcp MCP Server

Features

• Calendar management (events, reminders)

• Clipboard operations

• Finder integration

• System notifications

• System controls (volume, dark mode, apps)

• iTerm terminal integration

• Mail (create new email, list emails, get email)

• Shortcuts automation

• Messages (list chats, get messages, search messages, send a message)

• Notes (create formatted notes, list notes, search notes)

• Pages (create documents)

Planned Features

• Safari (open in Safari, save page content, get selected page/tab)

• Reminders (create, get)

Prerequisites

• macOS 10.15 or later

• Node.js 18 or later

Available Categories

Calendar

Examples

Clipboard

Examples

Finder

Examples

Notifications

Note: Sending notification requires that you enable notifications in System Settings > Notifications > Script Editor.

Examples

System

Examples

iTerm

Examples

Shortcuts

Examples

Mail

Examples

Messages

Examples

Notes

Examples

Pages

Examples

Architecture

Core Components

1. AppleScriptFramework (framework.ts): The main server class that:

2. Categories (src/categories/*.ts): Modular script collections organized by functionality:

3. Types (src/types/index.ts): TypeScript interfaces defining:

Execution Flow

1. Client sends a tool request via MCP protocol

2. Server identifies the appropriate category and script

3. Script content is generated (static or dynamically via function)

4. AppleScript is executed via macOS osascript command

5. Results are returned to the client

Logging System

• Logs to both stderr and MCP logging protocol

• Supports multiple severity levels (debug, info, warning, error, etc.)

• Provides detailed execution information for troubleshooting

Development

Setup

Adding New Functionality

1. Create Category File

2. Add Scripts

3. Register Category

Advanced Script Development

1. Use dynamic script generation:

2. Process complex data:

Debugging

Using MCP Inspector

Logging

Example configuration

Common Issues

• Permission Errors: Check System Preferences > Security & Privacy > Privacy > Automation

• Script Failures: Test scripts directly in Script Editor.app before integration

• Communication Issues: Check stdio streams aren't being redirected

• Database Access: Some features (like Messages) require Full Disk Access permission

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

applescript-mcp MCP Server

Features

• Calendar management (events, reminders)

• Clipboard operations

• Finder integration

• System notifications

• System controls (volume, dark mode, apps)

• iTerm terminal integration

• Mail (create new email, list emails, get email)

• Shortcuts automation

• Messages (list chats, get messages, search messages, send a message)

• Notes (create formatted notes, list notes, search notes)

• Pages (create documents)

Planned Features

• Safari (open in Safari, save page content, get selected page/tab)

• Reminders (create, get)

Prerequisites

• macOS 10.15 or later

• Node.js 18 or later

Available Categories

Calendar

Examples

Clipboard

Examples

Finder

Examples

Notifications

Note: Sending notification requires that you enable notifications in System Settings > Notifications > Script Editor.

Examples

System

Examples

iTerm

Examples

Shortcuts

Examples

Mail

Examples

Messages

Examples

Notes

Examples

Pages

Examples

Architecture

Core Components

1. AppleScriptFramework (framework.ts): The main server class that:

2. Categories (src/categories/*.ts): Modular script collections organized by functionality:

3. Types (src/types/index.ts): TypeScript interfaces defining:

Execution Flow

1. Client sends a tool request via MCP protocol

2. Server identifies the appropriate category and script

3. Script content is generated (static or dynamically via function)

4. AppleScript is executed via macOS osascript command

5. Results are returned to the client

Logging System

• Logs to both stderr and MCP logging protocol

• Supports multiple severity levels (debug, info, warning, error, etc.)

• Provides detailed execution information for troubleshooting

Development

Setup

Adding New Functionality

1. Create Category File

2. Add Scripts

3. Register Category

Advanced Script Development

1. Use dynamic script generation:

2. Process complex data:

Debugging

Using MCP Inspector

Logging

Example configuration

Common Issues

• Permission Errors: Check System Preferences > Security & Privacy > Privacy > Automation

• Script Failures: Test scripts directly in Script Editor.app before integration

• Communication Issues: Check stdio streams aren't being redirected

• Database Access: Some features (like Messages) require Full Disk Access permission

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