applescript

This AppleScript MCP Server lets you run AppleScript code against macOS applications and data through the MCP protocol. It exposes common Mac automation capabilities such as interacting with Notes, Calendar, Contacts, and other apps, searching with Spotlight, reading and writing file contents, running shell commands, and supporting remote execution over SSH. The server is designed to be simple to run with dual access for Python (uvx/uv) and Node.js environments, enabling you to integrate AppleScript automation into your MCP workflow with minimal setup. You can use the provided prompts to create reminders, manage calendars, manipulate notes, or retrieve system information from a macOS host.

To use it, start the MCP server via your preferred runtime (npx for Node.js, uv/uvx for Python), and then issue MCP-style requests to the endpoint defined by the server. The included examples demonstrate typical automation tasks such as creating calendar events, querying files, listing applications, capturing screenshots, and accessing contacts. The Docker usage section shows how to connect from within a container to a macOS host using SSH, enabling remote AppleScript execution from isolated environments.

Prerequisites:

• macOS machine to run AppleScript and host the service
• Node.js (for npx) or Python with uv/uvx installed if you choose the Python route
• Internet access to fetch the MCP package from npm when using npx

Option A: Run via Node.js (npx)

1. Ensure Node.js is installed on your machine.
2. Run the MCP server with the package via npx:
   • npx @peakmojo/applescript-mcp
3. The server will start and expose MCP endpoints for executing AppleScript commands.

Option B: Run via Python (uvx)

1. Ensure Python is installed along with uv/uvx support.
2. Run directly from the git repo or install if needed (see repo specifics):
   • uvx --from git+https://github.com/peakmojo/applescript-mcp mcp-server-applescript
3. For local development, clone the repo and run from source using uv:
   • git clone https://github.com/peakmojo/applescript-mcp.git
   • uv --directory /path/to/your/repo run mcp-server-applescript

Optional: Docker

• If you run inside Docker, configure the host connection to the Mac using the provided example and ensure SSH access is enabled on the Mac host. See the Docker Usage section in the README for details on --remoteHost, --remoteUser, and --remotePassword.

Tips and considerations:

• When using the Node.js npx approach, you can immediately start the server without a local install, which is convenient for testing.
• The Python uvx/uv approaches support running directly from the git repo, making it easy to pull latest changes during development.
• For Docker deployments, you must enable SSH on the Mac host and provide correct credentials in the MCP configuration to allow remote AppleScript execution.
• If you encounter permissions issues on macOS, ensure the AppleScript has appropriate privileges and that the user running the MCP server has access to the target applications.
• The MCP server supports a range of AppleScript interactions; start with simple scripts (e.g., show list of running applications) before attempting complex automation.
• Always validate your AppleScript syntax separately to avoid runtime errors when invoked via MCP.