The AppleScript MCP Server allows you to run AppleScript code to interact with Mac applications and system features, including:
Retrieve or create notes in Apple Notes
Access or add calendar events and appointments
List contacts or modify contact details
Search for and organize files using Spotlight or Finder
Get system information like battery status, disk space, or network details
Access or send emails, messages, or other communications
Read, write, or manage file contents
Execute shell commands and capture the output
Control media playback in applications like Apple Music
Take screenshots
Open applications and navigate to URLs
Supports remote execution via SSH
Provides comprehensive access to macOS functionality through AppleScript, allowing interaction with the Mac operating system and its applications.
Enables control of Apple Music, including playing playlists as mentioned in the example prompt.
Provides access to the MCP server functionality through Node.js, allowing JavaScript-based interaction with macOS.
Provides access to the MCP server functionality through Python, offering an alternative programming interface for macOS automation.
Allows automation of Safari web browser, including opening the browser and navigating to websites.
Allows execution of shell commands on macOS, providing access to command-line utilities and system information.
Enables file searching using macOS Spotlight technology to locate files across the system.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AppleScript MCP Servercreate a new note titled 'Shopping List' with eggs, milk, and bread"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AppleScript MCP Server (Dual access: python and node.js)
Overview
A Model Context Protocol (MCP) server that lets you run AppleScript code to interact with Mac. This MCP is intentionally designed to be simple, straightforward, intuitive, and require minimal setup.
I can't believe how simple and powerful it is. The core code is <100 line of code.
https://github.com/user-attachments/assets/b85e63ba-fb26-4918-8e6d-2377254ee388
Related MCP server: Xcode MCP Server
Features
Run AppleScript to access Mac applications and data
Interact with Notes, Calendar, Contacts, Messages, and more
Search for files using Spotlight or Finder
Read/write file contents and execute shell commands
Remote execution support via SSH
Example Prompts
Create a reminder for me to call John tomorrow at 10amAdd a new meeting to my calendar for Friday from 2-3pm titled "Team Review"Create a new note titled "Meeting Minutes" with today's dateShow me all files in my Downloads folder from the past weekWhat's my current battery percentage?Show me the most recent unread emails in my inboxList all the currently running applications on my MacPlay my "Focus" playlist in Apple MusicTake a screenshot of my entire screen and save it to my DesktopFind John Smith in my contacts and show me his phone numberCreate a folder on my Desktop named "Project Files"Open Safari and navigate to apple.comTell me how much free space I have on my main driveList all my upcoming calendar events for this weekUsage with Claude Desktop
Node.js
{
"mcpServers": {
"applescript_execute": {
"command": "npx",
"args": [
"@peakmojo/applescript-mcp"
]
}
}
}Python (uvx)
No clone needed — run directly from the git repo:
{
"mcpServers": {
"applescript_execute": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/peakmojo/applescript-mcp",
"mcp-server-applescript"
]
}
}
}Python (local development)
For local development, clone the repo and use uv to run from source:
brew install uv
git clone https://github.com/peakmojo/applescript-mcp.git{
"mcpServers": {
"applescript_execute": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/repo",
"run",
"mcp-server-applescript"
]
}
}
}Development
Setup
brew install uv
uv sync --devRun all checks (in parallel)
uv run checkThis runs linting, formatting, type checking, and tests with 100% coverage — all in parallel.
Individual commands
uv run lint # ruff linter
uv run format # ruff auto-format
uv run typecheck # pyrefly type checker
uv run test # pytest with 100% coverage enforcementDocker Usage
When running in a Docker container, you can use the special hostname host.docker.internal to connect to your Mac host:
Configuration
{
"mcpServers": {
"applescript_execute": {
"command": "npx",
"args": [
"@peakmojo/applescript-mcp",
"--remoteHost", "host.docker.internal",
"--remoteUser", "yourusername",
"--remotePassword", "yourpassword"
]
}
}
}This allows your Docker container to execute AppleScript on the Mac host system. Make sure:
SSH is enabled on your Mac (System Settings → Sharing → Remote Login)
Your user has proper permissions
The correct credentials are provided in the config