applescript-mcp

To allow a Docker container to execute AppleScript on your Mac host, use the host.docker.internal hostname and provide SSH credentials.

Prerequisites:

1. Enable SSH on your Mac: System Settings → Sharing → Remote Login.
2. Ensure your user has proper permissions.
3. Provide correct credentials in the configuration.

Configuration: Replace yourusername and yourpassword with your actual Mac credentials.

{
  "mcpServers": {
    "applescript_execute": {
      "command": "npx",
      "args": [
        "@peakmojo/applescript-mcp",
        "--remoteHost", "host.docker.internal",
        "--remoteUser", "yourusername",
        "--remotePassword", "yourpassword"
      ]
    }
  }
}

To use the AppleScript MCP server via Node.js in Claude Desktop, add the following configuration to your claude_desktop_config.json. This method uses npx to run the @peakmojo/applescript-mcp package directly.

{
  "mcpServers": {
    "applescript_execute": {
      "command": "npx",
      "args": [
        "@peakmojo/applescript-mcp"
      ]
    }
  }
}

To use the AppleScript MCP server via Python without cloning the repository, use uvx to run it directly from the GitHub repository. Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "applescript_execute": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/peakmojo/applescript-mcp",
        "mcp-server-applescript"
      ]
    }
  }
}

The project uses uv to manage development tasks. You can run all checks in parallel or run specific tools individually.

Run all checks (linting, formatting, type checking, and tests):

uv run check

Individual commands:

• uv run lint: Runs the ruff linter.
• uv run format: Runs ruff auto-format.
• uv run typecheck: Runs the pyrefly type checker.
• uv run test: Runs pytest (enforces 100% coverage).

To develop on this project, install uv and sync the dependencies:

brew install uv
uv sync --dev

If you are developing locally, clone the repository and use uv to run the server from the source directory. Replace /path/to/your/repo with the actual absolute path to your cloned repository in the configuration below:

{
  "mcpServers": {
    "applescript_execute": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/repo",
        "run",
        "mcp-server-applescript"
      ]
    }
  }
}

Once the MCP server is connected, you can use natural language prompts to perform Mac tasks. Examples include:

• Calendar/Reminders: Add a new meeting to my calendar for Friday from 2-3pm titled "Team Review" or Create a reminder for me to call John tomorrow at 10am.
• Files/System: Show me all files in my Downloads folder from the past week or What's my current battery percentage?.
• Applications: Play my "Focus" playlist in Apple Music or Open Safari and navigate to apple.com.
• Notes/Contacts: Create a new note titled "Meeting Minutes" with today's date or Find John Smith in my contacts and show me his phone number.
• Media/Screenshots: Take a screenshot of my entire screen and save it to my Desktop.

The server uses a custom logger that outputs to stderr. You can control the verbosity of the logs by setting the LOG_LEVEL environment variable.

Supported log levels (in order of increasing verbosity):

• ERROR (0)
• WARN (1)
• INFO (2)
• DEBUG (3)

If LOG_LEVEL is not set, the server defaults to INFO.

# Example: Running with DEBUG logging enabled
LOG_LEVEL=DEBUG node server.js

The server's logging level can be configured using the --log-level CLI flag or the LOG_LEVEL environment variable. Supported levels are standard Python logging levels (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL).

# Using environment variable
export LOG_LEVEL=DEBUG
python -m applescript_mcp.server

# Using CLI flag
python -m applescript_mcp.server --log-level DEBUG

The server exposes a single MCP tool named applescript_execute. This tool allows an AI agent to run multi-line AppleScript code to interact with macOS applications (Notes, Calendar, Finder, Safari, etc.) or the system itself.

Arguments

• code_snippet (string, required): The multi-line AppleScript code to be executed.
• timeout (number, optional): The command execution timeout in seconds. Defaults to 60.

Template Variables

If you are using remote execution, you can inject your SSH configuration into your AppleScript code using the following placeholders:

• {{REMOTE_HOST}}
• {{REMOTE_USER}}
• {{REMOTE_PASSWORD}}

{
  "name": "applescript_execute",
  "arguments": {
    "code_snippet": "tell application 'Finder' to get name of every disk",
    "timeout": 30
  }
}

You can start the AppleScript MCP server by calling the main() function from the applescript_mcp package. This function initializes the logging configuration (set to DEBUG level by default) and runs the asynchronous server loop using asyncio.run(server.main()).

from applescript_mcp import main

if __name__ == '__main__':
    main()