AppleScript MCP server
Lets an AI client run AppleScript on a Mac to control apps, files, reminders, calendars, messages, and shell commands.
Also known as peakmojo/applescript-mcp, @peakmojo/applescript-mcp
- Stars
- 468
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Feb 22, 2026
- License
- MIT
What is AppleScript MCP?
AppleScript lets an AI client run AppleScript on a Mac to control apps, files, reminders, calendars, messages, and shell commands.
Summary generated from the project's README
About AppleScript MCP server
Controlling macOS applications and system data through an AI client is possible with this MCP server. It enables users to execute AppleScript to manage files, reminders, calendars, messages, and notes directly from their chat interface. By bridging the gap between language models and the Mac operating system, it allows for automated interactions with native apps like Apple Music, Safari, and Contacts.
Developers can set this up locally using Node.js via npx or through Python using uvx. For those working within Docker containers, the server supports remote execution over SSH by connecting to the host machine. This setup requires enabling Remote Login in your Mac system settings and providing the necessary user credentials. The server provides a way to perform system tasks like checking battery percentage, searching for files with Spotlight, or running shell commands.
What you can do with it
- 1Manage personal schedules and tasksAsk the AI to add new meetings to your calendar or create specific reminders.
- 2Organize and search local filesRequest the AI to find specific files in your folders or create new directories on your desktop.
- 3Control media and system settingsInstruct the AI to play specific music playlists or check your hardware status.
- 4Automate communication and contact retrievalUse the AI to find phone numbers in your contacts or check unread messages.
Written from the project's README. Every use case is checked against a quote from it.
How to install AppleScript MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall AppleScript MCP in Claude Code
$ claude mcp add applescript-mcp -- npx -y @peakmojo/applescript-mcpInstall AppleScript MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"applescript-mcp": {
"command": "npx",
"args": [
"-y",
"@peakmojo/applescript-mcp"
]
}
}
}Install AppleScript MCP in VS Code
.vscode/mcp.json
{
"servers": {
"applescript-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@peakmojo/applescript-mcp"
]
}
}
}Install AppleScript MCP in VS Code CLI
$ code --add-mcp '{"name":"applescript-mcp","type":"stdio","command":"npx","args":["-y","@peakmojo/applescript-mcp"]}'Install AppleScript MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"applescript-mcp": {
"command": "npx",
"args": [
"-y",
"@peakmojo/applescript-mcp"
]
}
}
}Install AppleScript MCP in Codex
$ codex mcp add applescript-mcp -- npx -y @peakmojo/applescript-mcpInstall AppleScript MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.applescript-mcp] command = "npx" args = ["-y", "@peakmojo/applescript-mcp"]
Install AppleScript MCP in Gemini CLI
$ gemini mcp add -s user applescript-mcp npx -- -y @peakmojo/applescript-mcpInstall AppleScript MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"applescript-mcp": {
"command": "npx",
"args": [
"-y",
"@peakmojo/applescript-mcp"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepeakmojo/applescript-mcp is public and reachablegithub.com/peakmojo/applescript-mcp ↗Pass
- Package names this repository as its source@peakmojo/applescript-mcp names peakmojo/applescript-mcp as sourcenpmjs.com/package/@peakmojo/applescript-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-02-22github.com/peakmojo/applescript-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @peakmojo/applescript-mcpPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAppleScript 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
AppleScript MCP questions
How do I add AppleScript MCP to Claude Code?
Run claude mcp add applescript-mcp -- npx -y @peakmojo/applescript-mcp in your terminal. Add --scope user to make it available in every project.
How do I add AppleScript MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What can the AppleScript MCP server do on my Mac?
It runs AppleScript code to interact with Mac applications and data, including Notes, Calendar, Contacts, Messages, files, and shell commands.
How do I install the AppleScript MCP server with Claude Desktop?
Add it as an MCP server using npx with the package @peakmojo/applescript-mcp, or run the Python version with uvx from the git repo.
Can it work from inside a Docker container?
Yes, using the host.docker.internal hostname plus remote host, user, and password arguments, with SSH enabled on the Mac.
Does it support remote execution?
Yes, remote execution is supported via SSH with a remote host, user, and password.
Which command-line tool does the Python version need?
The Python version runs via uv, which can be installed with Homebrew.