AppleScript API to MCP server wrapper for Python

Introduction

This is a simple Python program that scans for the exposed interface of an macOS app and creates a wrapper for use in Python, as well as one to create as a FastMCP server so it can interface with Claude Code and other MCP clients. It will try to find the application and if found it will create three files, two Python classes and one JSON file with the same information it gathered. It hopefully work "out of the box" but because for MCP the descriptions may be too short, so additional information will help the LLM to pick the correct tools.

Requirements

• macOS (uses osascript and sdef)
• Python 3.10+
• FastMCP (pip install fastmcp) — only needed to run the MCP server

It uses new typing features from Python 3.10+, so if you want to remove them if you want to attempt to adapt to earlier versions.

Installation

git clone https://github.com/aredigg/MCP-server-AppleScript-wrapper.git mcp-osacreate
cd mcp-osacreate
chmod +x bin/mcp-osacreate

The python file is in the bin folder, and can either remain to be run locally or copied to a system path like /usr/local/bin like this (requires Administrator access)

sudo cp bin/mcp-osacreate /usr/local/bin/

Optional, only for MCP server usage

pip3 install fastmcp

Usage

> mcp_osacreate <ApplicationName>

macOS will ask for access to control the app in question, because it uses AppleScript to interrogate the app. This is a one time question, and will also apply for the MCP use if you decide to later.

Example

mcp_osacreate Finder

This creates three files:

File	Description
finder.py	Python class for direct use
finder_mcp.py	FastMCP server
finder.json	JSON API documentation

Using the JSON File

The JSON file contains the complete API documentation and can be used for reference, building custom tooling, feeding to an LLM for context or bedtime reading

Tips for Better LLM Integration

Enhancing Tool Descriptions

The generated MCP server uses descriptions from the app's SDEF dictionary, which can be sparse. Edit the docstrings in the generated *_mcp.py file to add more context:

# Before (auto-generated)
@mcp.tool()
def finder_open(direct: str) -> str:
    """Open an object."""
    ...

# After
@mcp.tool()
def finder_open(direct: str) -> str:
    """
    Open a file, folder, or application in Finder.

    Args:
        direct: Path to the item to open. Can be:
            - A file path: "/Users/me/document.pdf"
            - A folder path: "/Users/me/Documents"
            - An application: "/Applications/Safari.app"

    Returns:
        Empty string on success

    Examples:
        finder_open("/Users/me/Documents")
        finder_open("/Applications/Calculator.app")
    """
    ...

Warning

This can be a powerful tool, and AppleScript could have exposed interfaces that could potentially do unwanted or damaging actions, so absolutely do due dilligence before applying. I recommend removing all tool or methods that you don't need, or deem risky.

License

This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.