Control Mac Apps with Natural Language
MCP server that runs AppleScript to control Mac apps - Notes, Calendar, Contacts, Messages, Finder, Spotlight - plus shell commands and remote SSH.
Why it matters
Execute AppleScript commands on your Mac using natural language prompts. Interact with applications, files, and system functions to automate tasks and access data.
Outcomes
What it gets done
Control Mac applications like Calendar, Notes, and Contacts.
Search for files using Spotlight or Finder.
Read and write file contents.
Execute shell commands remotely via SSH.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/vb-apple-script | bash Capabilities
Tools your agent gets
Execute AppleScript code to interact with Mac applications, files, and system functions.
Search files via Spotlight or Finder on the Mac system.
Read file contents from the Mac filesystem.
Write or modify file contents on the Mac filesystem.
Execute shell commands on the Mac system.
Overview
AppleScript MCP Server
A minimal MCP server, under 100 lines of core code, that runs AppleScript to let an AI assistant control Mac apps like Notes, Calendar, Contacts, and Messages, search files, run shell commands, and execute scripts remotely over SSH. Use it for hands-on Mac automation, such as creating calendar events or notes, searching files, checking system status, or controlling apps, through natural language instead of writing AppleScript manually.
What it does
A deliberately minimal MCP server, with core logic under 100 lines of code, that lets an AI assistant run AppleScript to interact with a Mac directly. Rather than exposing a curated set of narrow tools, it gives the assistant the ability to script whatever AppleScript can already reach: native apps like Notes, Calendar, Contacts, and Messages, file search through Spotlight or Finder, reading and writing file contents, running shell commands, and checking system state like battery level or free disk space.
When to use - and when NOT to
Use it for hands-on Mac automation through natural language - creating a reminder or calendar event, drafting a note, finding files modified in the last week, checking unread email, or taking a screenshot - where AppleScript already has the reach to do it and writing the script by hand would be slower than describing the task. It is intentionally broad rather than sandboxed: because it executes arbitrary AppleScript and shell commands, it should be granted only to a trusted assistant and used with the same caution as any tool with shell access, not treated as a safely scoped, read-only integration. Remote execution over SSH extends its reach to a Mac host from inside a Docker container, which is powerful but means the SSH credentials configured for it deserve the same protection as any other remote-access secret.
Capabilities
Documented example tasks span native app control (create a reminder, add a calendar event, create a note, play a specific Apple Music playlist), file and system operations (search Downloads for recent files, take a full-screen screenshot to the Desktop, create a folder, check free disk space and battery percentage), information lookup (find a contact's phone number, list unread inbox emails, list running applications, list upcoming calendar events), and browser control (open Safari and navigate to a URL). All of these route through a single applescript_execute tool that runs the underlying script, rather than one dedicated tool per app.
How to install
Node.js version:
{
"mcpServers": {
"applescript_execute": {
"command": "npx",
"args": [
"@peakmojo/applescript-mcp"
]
}
}
}
Python version, no clone needed:
{
"mcpServers": {
"applescript_execute": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/peakmojo/applescript-mcp",
"mcp-server-applescript"
]
}
}
}
For Docker deployments, connect to the Mac host via host.docker.internal with SSH remote-execution arguments, after enabling Remote Login in System Settings.
Who it's for
Mac users who want an AI assistant to actually operate their system, apps, files, and settings, through natural language instead of manually running AppleScript or clicking through each app. The project is licensed under MIT.
Source README
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
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 10am
Add a new meeting to my calendar for Friday from 2-3pm titled "Team Review"
Create a new note titled "Meeting Minutes" with today's date
Show me all files in my Downloads folder from the past week
What's my current battery percentage?
Show me the most recent unread emails in my inbox
List all the currently running applications on my Mac
Play my "Focus" playlist in Apple Music
Take a screenshot of my entire screen and save it to my Desktop
Find John Smith in my contacts and show me his phone number
Create a folder on my Desktop named "Project Files"
Open Safari and navigate to apple.com
Tell me how much free space I have on my main drive
List all my upcoming calendar events for this week
Usage 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 --dev
Run all checks (in parallel)
uv run check
This 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 enforcement
Docker 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
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.