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 Server create 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.
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: macOS Automator MCP Server
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
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 week{
"mcpServers": {
"applescript_execute": {
"command": "npx",
"args": [
"@peakmojo/applescript-mcp"
]
}
}
}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"
]
}
}
}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"
]
}
}
}brew install uv
uv sync --devuv run checkThis runs linting, formatting, type checking, and tests with 100% coverage — all in parallel.
uv run lint # ruff linter
uv run format # ruff auto-format
uv run typecheck # pyrefly type checker
uv run test # pytest with 100% coverage enforcementWhen running in a Docker container, you can use the special hostname host.docker.internal to connect to your Mac host:
{
"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
Run AppleScript code to interact with Mac applications and system features. This tool can access and manipulate data in Notes, Calendar, Contacts, Messages, Mail, Finder, Safari, and other Apple applications. Common use cases include but not limited to: - 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 - Read or organize browser bookmarks or history - Access or send emails, messages, or other communications - Read, write, or manage file contents - Execute shell commands and capture the output
| Name | Required | Description | Default |
|---|---|---|---|
| code_snippet | Yes | Multi-line appleScript code to execute | |
| timeout | No | Command execution timeout in seconds (default: 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions capabilities like manipulating data and executing commands, but fails to disclose critical traits such as security implications, permission requirements, error handling, or potential side effects (e.g., data modification risks). This leaves significant gaps for a tool with broad system access.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose and followed by a bulleted list of use cases. While the list is extensive, each item earns its place by illustrating the tool's scope, making it efficient for understanding capabilities without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (broad system access, 2 parameters, no annotations, no output schema), the description is partially complete. It covers purpose and use cases well but lacks behavioral details (e.g., safety, errors) and output information. This is adequate for basic understanding but insufficient for fully informed usage without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents both parameters (code_snippet and timeout). The description does not add any meaning beyond what the schema provides, such as syntax examples or best practices for AppleScript code. Baseline 3 is appropriate as the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Run AppleScript code') and resource ('Mac applications and system features'), and distinguishes it from potential siblings by listing comprehensive capabilities like interacting with Notes, Calendar, Contacts, Finder, Safari, and executing shell commands. It goes beyond a tautology by detailing what the tool can achieve.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through examples of common use cases (e.g., retrieve notes, access calendar events, execute shell commands), but it does not explicitly state when to use this tool versus alternatives or provide exclusions. With no sibling tools, the guidance is adequate but lacks explicit context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
With only one tool, there is no possibility of confusion or overlap between tools, making disambiguation perfect. The single tool 'applescript_execute' has a clear and distinct purpose, covering all AppleScript-related operations without any competing alternatives.
The naming is trivially consistent as there is only one tool, 'applescript_execute', which follows a clear verb_noun pattern. No inconsistencies can exist in a single-tool set, so it meets the highest standard for naming predictability.
A single tool for a server that interacts with multiple Mac applications and system features feels too thin and under-scoped. The tool count of 1 is borderline for any non-trivial domain, as it forces all operations through a single interface, which may limit clarity and efficiency for agents.
The tool surface is notably incomplete for the domain of Mac application and system interaction. While 'applescript_execute' can handle many tasks via scripting, there are obvious gaps in structured operations like dedicated CRUD for specific resources (e.g., notes, contacts), which could lead to agent inefficiencies or failures in complex workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/peakmojo/applescript-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
