Skip to main content
Glama
pietz

MCP AppleScript

by pietz
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

MCP AppleScript

An MCP (Model Context Protocol) server that enables Large Language Models to execute AppleScript commands on macOS. This allows LLMs to interact with and automate macOS applications through natural language requests.

Features

  • Execute AppleScript commands from LLM applications

  • Application allowlist for controlled access to specific apps

  • Dangerous pattern detection to block risky operations

  • Configurable timeout protection

  • Built on FastMCP for easy integration

Related MCP server: osascript MCP Server

Installation

Using uv:

uv pip install mcp-applescript

Or install from source:

git clone https://github.com/pietz/mcp-applescript.git
cd mcp-applescript
uv sync

Usage

Running the Server

mcp-applescript

The server runs using stdio transport, making it compatible with any MCP client.

Available Tools

run_applescript

Execute an AppleScript command on macOS.

Parameters:

  • script (string): The AppleScript code to execute

Returns:

  • String output from the script execution

  • Raises error if script fails validation or execution

Example:

tell application "Mail"
    get subject of first message of inbox
end tell

get_server_status

Get the current server configuration and security settings.

Returns:

  • Server version and configuration

  • Allowed applications list

  • Security settings (dangerous pattern blocking, timeout)

  • Environment variable documentation

Example Response:

{
  "server": "MCP AppleScript",
  "version": "0.1.0",
  "security": {
    "allowed_apps": ["Mail", "Calendar"],
    "block_dangerous": true,
    "timeout_seconds": 30
  }
}

Configuration

MCP Client Setup

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "applescript": {
      "command": "mcp-applescript",
      "env": {
        "ALLOWED_APPS": "mail,calendar,contacts,notes",
        "BLOCK_DANGEROUS": "true"
      }
    }
  }
}

Environment Variables

ALLOWED_APPS (optional)

  • Comma-separated list of allowed applications (case-insensitive)

  • Example: "mail,calendar,contacts" (lowercase recommended)

  • Not set (default): Allows all applications ("*")

  • "*": Explicitly allows all applications

  • "" (empty string): Blocks all applications (lockdown mode)

  • Security Note: Set this to restrict access to specific apps only

  • App names are automatically normalized to title case for AppleScript

BLOCK_DANGEROUS (optional)

  • Enable/disable dangerous pattern detection

  • Values: "true" or "false"

  • Default: "true"

  • Blocks patterns like: do shell script, file system access, system control commands

TIMEOUT (optional)

  • Script execution timeout in seconds

  • Default: "30"

Security Profiles

Default (Out of the Box)

"env": {
  // ALLOWED_APPS not set = allow all apps
  "BLOCK_DANGEROUS": "true"  // This is the default, can be omitted
}

  • ✅ Works immediately without configuration

  • ✅ Dangerous operations blocked

  • ⚠️ Can access any application

Strict (Recommended for Production)

"env": {
  "ALLOWED_APPS": "mail,calendar,contacts",
  "BLOCK_DANGEROUS": "true"
}

  • ✅ Limited to specific applications

  • ✅ Dangerous operations blocked

  • ✅ Best security posture

Permissive (Development/Testing Only)

"env": {
  "ALLOWED_APPS": "*",  // or omit this line
  "BLOCK_DANGEROUS": "false"
}

  • ⚠️ Can access any application

  • ⚠️ Dangerous operations allowed

  • ⚠️ Use only in trusted environments

Lockdown (Explicit Block)

"env": {
  "ALLOWED_APPS": ""  // Empty string = block all
}

  • 🔒 Blocks all AppleScript execution

  • Useful for temporary disabling

Security

Built-in Protections

  1. Application Allowlist (optional)

    • Default: All applications allowed (for usability)

    • Configure ALLOWED_APPS to restrict to specific applications

    • Prevents unauthorized access to system apps when configured

  2. Dangerous Pattern Detection

    • Blocks shell command execution (do shell script)

    • Prevents system control operations (shutdown, restart, logout)

    • Blocks access to sensitive paths (/System, /Library, ~/.ssh)

    • Detects potential phishing (password dialogs)

    • Prevents file deletion operations

  3. Execution Timeout

    • Prevents infinite loops and hanging scripts

    • Configurable timeout duration

Blocked Operations Examples

-- ❌ BLOCKED: Shell command execution
do shell script "rm -rf ~/"

-- ❌ BLOCKED: System control
tell application "System Events" to shut down

-- ❌ BLOCKED: Sensitive file access
do shell script "cat ~/.ssh/id_rsa"

-- ❌ BLOCKED: Unauthorized application (if not in ALLOWED_APPS)
tell application "Terminal" to do script "echo test"

-- ✅ ALLOWED: Reading from allowed app
tell application "Mail"
    get subject of first message of inbox
end tell

Best Practices

  • Configure application allowlist: Set ALLOWED_APPS to only the applications you need for production use

  • Keep dangerous blocking enabled: Default is on - provides essential protection

  • Review server status: Use get_server_status tool to understand current configuration

  • Principle of least privilege: In production, only allow the minimum necessary applications

  • Start permissive, then restrict: Begin with defaults, then lock down based on actual usage

Usage Examples

Check Server Configuration

Before running scripts, check what's allowed:

User: "What can you access on my system?"

LLM uses: get_server_status()

Response: "I can currently access: Mail, Calendar, and Contacts.
Dangerous operations are blocked, and scripts timeout after 30 seconds."

Read Mail (Allowed)

tell application "Mail"
    get subject of first message of inbox
end tell

Get Calendar Events (Allowed)

tell application "Calendar"
    get summary of every event of calendar "Work"
end tell

System Information (Blocked - Security)

-- This will be BLOCKED if "System Events" not in ALLOWED_APPS
tell application "System Events"
    name of first process whose frontmost is true
end tell

Display Notification (Safe)

-- Safe if no dangerous patterns
display notification "Hello from MCP!" with title "AppleScript"

Requirements

  • Python >= 3.12

  • macOS (AppleScript is macOS-only)

  • mcp >= 1.13.1

License

MIT

Author

Paul-Louis Pr�ve

Available Tools

2 tools
run_applescriptA

Execute AppleScript commands on macOS. Use 'tell application "AppName"' to control apps. Multi-line scripts supported. Returns plain text output, truncated to 10,000 chars for large results.

ParametersJSON Schema
NameRequiredDescriptionDefault
scriptYesAppleScript code to execute.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that output is plain text and truncated to 10,000 characters. However, it lacks warnings about potential destructive side effects of executing arbitrary AppleScript commands, which is a significant oversight given no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with the core purpose, and every sentence provides useful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single parameter and an output schema, the description sufficiently covers usage and output behavior. Missing error handling context, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers the 'script' parameter with a description. The description adds value by providing usage tips for typical AppleScript patterns, going beyond the schema's basic definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Execute' and resource 'AppleScript commands on macOS', clearly defining the tool's purpose. With only one sibling tool ('status'), there is no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear guidance on usage patterns, such as using 'tell application' and support for multi-line scripts. However, it does not specify when not to use the tool or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statusA

Returns the list of allowed apps and whether dangerous command blocking is enabled.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description indicates a read-only operation ('Returns'). It does not disclose permissions or potential side effects, but for a status query with no parameters, the behavioral disclosure is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that is concise and front-loaded with the action and key outputs. No extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of parameters and output schema, the description effectively explains what the tool returns. It covers the main outputs, though the format of the list or boolean is not specified, which is acceptable for this simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist (input schema empty, 100% coverage by default). The description does not need to explain parameters, so the baseline score of 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns 'the list of allowed apps' and 'whether dangerous command blocking is enabled', specifying both the action (returns) and the resources. This is specific and distinguishes from the sibling tool 'run_applescript'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The sibling is 'run_applescript', which is a different function, so usage context is implied as a status check, but no when-not or conditional advice is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.3
    • First observedrun_applescript
    • First observedstatus
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

The two tools have completely distinct purposes: run_applescript executes scripts and status returns configuration. No ambiguity in choice.

Naming Consistency5/5

Both tools follow a consistent snake_case verb_noun pattern ('run_applescript' and 'status'), making naming predictable.

Tool Count2/5

With only 2 tools, the server feels under-scoped for a typical CLI execution domain, which usually expects 3-15 tools for full interaction.

Completeness2/5

The domain of AppleScript execution is incompletely covered; missing tools for listing scripts, managing permissions, or retrieving error details leave agents with limited workflows.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • osascript MCP Server

    Akira-Papa
    F
    license
    A
    quality
    D
    maintenance
    Enables the execution of AppleScript and JavaScript for Automation (JXA) on macOS to control applications, system events, and shell commands. It provides native automation capabilities with a security layer that permits most operations while specifically blocking file deletion commands.
    1
    6
    -

  • Automation MCP

    ashwwwin
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables AI assistants to automate macOS desktop tasks including mouse control, keyboard input, screenshots, window management, and UI interaction.
    14
    414
    MIT

  • iac-mcp

    jsavin
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI to dynamically discover and control native macOS applications (like Finder, Mail, Safari) through AppleScript/JXA automation without pre-built integrations.
    3
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pietz/mcp-applescript'

If you have feedback or need assistance with the MCP directory API, please join our Discord server