How do I use mcp-server-osascript?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-server-osascript tell Finder to make new folder on desktop" 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.

mcp-server-osascript

by FradSer

Overview Schema Related Servers Score Discussions

Python

Local

MCP osascript Server

中文版

Secure AppleScript execution for AI applications via Model Context Protocol with configurable security profiles and automatic TCC permission handling.

Overview

This MCP server provides a bridge between AI models and macOS automation through secure AppleScript execution. It features a modular architecture with configurable security profiles, automatic permission management, and comprehensive error handling.

Related MCP server: macOS Automator MCP Server

Installation

Development Setup

# Clone and setup dependencies
uv sync

# Optional: Development mode installation
uv pip install -e .

Production Installation

# System-wide installation with uvx
uvx install /path/to/mcp-server-osascript

# From Git repository
uvx install git+https://github.com/your-username/mcp-server-osascript.git

# From PyPI (when published)
uvx install mcp-server-osascript

Usage

Production Usage

# After uvx installation (available system-wide)
mcp-server-osascript

Development Usage

# From project directory
uv run mcp-server-osascript

# From any directory
uv run --project /path/to/mcp-server-osascript mcp-server-osascript

# Alternative: Direct module execution
uv run python -m mcp_server_osascript.server

MCP Client Configuration

Add this configuration to your MCP client:

Production Configuration:

{
  "mcpServers": {
    "osascript": {
      "command": "mcp-server-osascript",
      "args": []
    }
  }
}

Development Configuration:

{
  "mcpServers": {
    "osascript": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/mcp-server-osascript", "mcp-server-osascript"]
    }
  }
}

Architecture

The server is built with a modular architecture consisting of six focused components:

Security System: Configurable risk assessment with three security profiles
Execution Engine: Direct osascript execution with timeout management
Permission Handler: Automatic TCC permission dialog triggering
Response Builder: Standardized API response formatting
User Interface: Interactive confirmation dialogs
Server Core: FastMCP integration and tool registration

Features

Configurable Security Profiles

Strict: Maximum security with blocked dangerous operations
Balanced: Recommended default with risk warnings (default)
Permissive: Minimal restrictions with audit logging

Advanced Permission Management

Automatic TCC permission dialog triggering
Intelligent error parsing and user guidance
Support for common macOS applications
Manual permission configuration instructions

Comprehensive Tool Interface

Single unified execute_osascript tool
Dry-run mode for script analysis without execution
Configurable execution timeouts
Detailed success and error reporting

Tool Reference

`execute_osascript`

Execute or analyze AppleScript/JavaScript code with comprehensive security and permission handling.

Parameters:

script (str): AppleScript or JavaScript code to execute
execution_timeout (int): Timeout in seconds (default: 30)
security_profile (str): Security level - "strict", "balanced", or "permissive" (default: "balanced")
enable_auto_permissions (bool): Auto-trigger TCC permission dialogs (default: true)
dry_run (bool): Analyze script without executing (default: false)

Response Structure:

{
  "status": "success|error",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "data": {
    "stdout": "execution output",
    "stderr": "error output",
    "execution_time": 1.23
  }
}

Error Response:

{
  "status": "error",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "error": {
    "type": "SECURITY_BLOCKED|TCC_PERMISSION_DENIED|EXECUTION_TIMEOUT|SYNTAX_ERROR",
    "message": "Human-readable error description",
    "details": "Additional error context and repair suggestions"
  }
}

Security Features

Script Analysis

Pattern matching for dangerous operations
Risk scoring and classification
High-risk operation confirmation prompts
Comprehensive audit logging

Permission Management

TCC error code detection (-1743)
Application-specific permission guidance
Automatic permission dialog triggering
Manual configuration instructions

Execution Safety

Direct execution for proper TCC dialog display
Configurable timeout protection
Subprocess error handling
Memory and resource management

System Requirements

Operating System: macOS (required for AppleScript runtime)
Python: 3.10 or higher
Package Manager: uv (recommended) or pip
Permissions: User must grant necessary TCC permissions for target applications

Development

Testing

# Validate syntax for all modules
python3 -m py_compile mcp_server_osascript/*.py

# Test individual modules
python3 -c "from mcp_server_osascript.security import SecurityProfileManager; print('Security module OK')"

Architecture Overview

The codebase follows a modular design with clear separation of concerns:

Security assessment and policy enforcement
Script execution and subprocess management
Permission handling and TCC error parsing
Standardized response formatting
User interface and confirmation dialogs

License

MIT License

Available Tools

3 tools

execute_osascriptA

    Execute or analyze scripts using osascript with comprehensive functionality and automatic permission handling.

    This unified tool handles both AppleScript/JavaScript execution and security analysis with full osascript
    capabilities including shell script execution and intelligent TCC permission management.

    Security Profiles:
    - "strict": Maximum security, blocks potentially dangerous operations
    - "balanced": Recommended default, warns about risks but allows execution
    - "permissive": Minimal restrictions, full functionality with audit logging

    Features:
    - Complete osascript support for AppleScript and JavaScript
    - Shell script execution via "do shell script"
    - Automatic TCC permission dialog handling
    - Intelligent error recovery and user guidance
    - Security risk assessment and warnings
    - Comprehensive execution logging
    - Dry-run mode for analysis without execution

    Args:
        script: The script code to execute or analyze (AppleScript or JavaScript for osascript)
        execution_timeout: Maximum execution time in seconds (default: 30, ignored in dry_run)
        security_profile: Security mode ("strict", "balanced", "permissive")
        enable_auto_permissions: Automatically handle macOS permission dialogs (default: True)
        dry_run: If True, only analyze security without executing (default: False)

    Returns:
        Standardized response with execution results, security analysis, and guidance

ParametersJSON Schema

Name	Required	Default
`script`	Yes
`dry_run`	No
`security_profile`	No	balanced
`execution_timeout`	No
`enable_auto_permissions`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior4/5

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

No annotations are provided, so the description carries full behavioral disclosure. It explicitly mentions automatic TCC permission dialog handling, dry-run mode, security risk assessment, error recovery, and logging—significant behavioral details beyond simple execution. It does not cover every possible side effect, but the disclosure is substantial and well above a bare-bones description.

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

Conciseness4/5

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

The description is organized with clear sections (Security Profiles, Features, Args, Returns) and front-loads the core purpose. Some redundancy exists (e.g., Features list partially repeats Args), but each section contains necessary information for a complex tool without excessive verbosity.

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 tool's complexity (5 parameters, output schema present), the description covers the main behavioral aspects: execution scope, security modes, dry-run, and return type. It does not delve into all edge cases or output schema specifics, but the combination of features, security profiles, and parameter explanations provides a solid contextual foundation for invocation.

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

Parameters5/5

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

Schema description coverage is 0%, but the description fully compensates with an 'Args:' section defining each parameter (script, execution_timeout, security_profile, enable_auto_permissions, dry_run) including defaults and allowed security profile values. This adds meaning beyond the schema, which only lists properties without descriptions.

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 opens with 'Execute or analyze scripts using osascript with comprehensive functionality and automatic permission handling,' which clearly identifies the action (execute/analyze), resource (osascript scripts), and distinguishes from siblings by also covering security analysis and profile handling. The tool's unified nature makes its purpose unambiguous.

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?

The description explains security profiles and dry-run mode but never explicitly states when to choose this tool over the sibling tools get_security_profiles or set_security_profile. Usage context is implied through features, but there are no direct alternatives, exclusions, or selection criteria provided.

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

get_security_profilesA

    Get information about all available security profiles.

    Returns detailed information about each security profile including their
    patterns, risk levels, and usage recommendations.

    Returns:
        Dictionary with security profile information and current configuration

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior3/5

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 disclosing behavior. The verb 'get' implies a read-only operation, and the mention of 'Returns' indicates no side effects, but there is no explicit statement about permissions, side effects, or data freshness. This is adequate but lacks the richness seen in well-disclosed tools.

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?

The description is three sentences: the first gives the main purpose, the second elaborates on the content, and the third states the return type. Every sentence earns its place without redundancy, and the key purpose is front-loaded in the first sentence.

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

Completeness5/5

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

Given that this is a simple zero-parameter getter with an output schema present, the description is complete. It covers what the tool does and what it returns, and the lack of usage guidance is not a completeness gap for such a straightforward operation. The output schema already provides structural detail.

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 tool has zero parameters and the schema provides 100% coverage (empty object). With 0 params, the baseline is 4. The description correctly adds no parameter details because there are none, and the return description is sufficient for the tool's purpose.

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 'Get information about all available security profiles' with a specific verb (get) and resource (security profiles). It distinguishes itself from the sibling tool set_security_profile by focusing on retrieval rather than modification, and the scope 'all available' is clear.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention set_security_profile or any conditions under which this getter should be invoked, such as before setting a profile. The agent must infer usage solely from the tool name and sibling names.

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

set_security_profileA

    Set the default security profile for script execution.

    This sets the default security profile that will be used when no explicit
    profile is specified in execute_applescript calls.

    Args:
        security_profile: Security profile to set as default ("strict", "balanced", "permissive")

    Returns:
        Confirmation of the configuration change

ParametersJSON Schema

Name	Required	Description	Default
`security_profile`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.6/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses that the tool changes the default configuration and that the effect is scoped to calls lacking an explicit profile. It also discloses the return value. It does not mention side effects or permissions, but for a configuration setter, this 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?

The description is compact and front-loaded. The first sentence states the core purpose, followed by a clarifying sentence about when it applies, and then a well-structured Args/Returns section. Every sentence contributes value without fluff.

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

Completeness5/5

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

For a single-parameter setter with an output schema, the description covers the action, condition of applicability, parameter values, and return behavior. It is complete in context; no additional details are needed for the agent to use this tool safely and correctly.

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

Parameters5/5

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

The input schema only provides a string type with no description or enum. The description compensates by listing the allowed values: 'strict', 'balanced', 'permissive'. This is essential information for the agent to invoke the tool correctly and is not present in the schema.

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's action: 'Set the default security profile for script execution.' This is a specific verb+resource. It distinguishes itself from siblings by referencing execute_applescript and implying get_security_profiles is for retrieval, so 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?

The description explains when this setting applies: 'when no explicit profile is specified in execute_applescript calls.' This provides clear context for usage. It does not explicitly name alternatives or exclusions, but the context is sufficient for a simple setter.

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.

3 tool updatesv0.1.0Aug 13, 2026
- First observedexecute_osascript
- First observedget_security_profiles
- First observedset_security_profile

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: execute_osascript for running scripts, get_security_profiles for listing profiles, and set_security_profile for changing the default. There is no functional overlap between them.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern (execute_osascript, get_security_profiles, set_security_profile), making the naming predictable and easy to learn.

Tool Count5/5

Three tools is an appropriate size for this focused server, covering the core execution capability and necessary security configuration without unnecessary bloat.

Completeness5/5

The server provides complete lifecycle coverage for its domain: executing scripts (with dry-run and security profiles), reading available security profiles, and updating the default profile. There are no obvious missing operations for this purpose.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Related MCP Connectors

SentinelX MCPOAuth
app.sentinelx
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Shell Access OS Automation
26
shortcuts-bridgeOAuth
io.github.IsaiahDupree
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
App Automation OS Automation
1
local-mcp A
com.local-mcp
Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.
Email Calendar Management File Systems
2033
hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
237

Related MCP Servers

AppleScript MCP Server
OS Automation App Automation Developer Tools
peakmojo
A
license
A
quality
F
maintenance
A Model Context Protocol server that enables running AppleScript code to interact with Mac applications and system features including Notes, Calendar, Contacts, Messages, file management, and more.
Updated 6 months ago (2026-02-22 03:24 UTC)
1
123
463
MIT
macOS Automator MCP Server
OS Automation App Automation Command Line
steipete
A
license
A
quality
A
maintenance
Provides a Model Context Protocol server for executing AppleScript and JavaScript for Automation scripts on macOS, featuring a knowledge base of pre-defined scripts and supporting automation of macOS applications and system functions.
Updated 2 days ago (2026-09-04 11:07 UTC)
2
1,294
878
MIT
macOS Automator MCP Server
OS Automation Developer Tools
SuperCrazyKaizen
A
license
A
quality
D
maintenance
A Model Context Protocol server that enables execution of AppleScript and JavaScript for Automation scripts on macOS, allowing programmatic control of applications and system functions through a rich knowledge base of pre-defined scripts.
Updated 9 months ago (2025-12-01 23:30 UTC)
2
1,294
8
MIT
MCP AppleScript
OS Automation App Automation Developer Tools
pietz
A
license
A
quality
C
maintenance
Enables Large Language Models to automate macOS applications and execute AppleScript commands through natural language. It features built-in security protections including application allowlists and dangerous pattern detection to prevent unauthorized or risky system operations.
Updated a year ago (2025-09-30 13:55 UTC)
2
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/FradSer/mcp-server-osascript'

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