JCAppleScript MCP server

JCAppleScript

A Swift package for executing AppleScript from macOS applications, featuring a built-in MCP server that lets AI assistants control macOS apps through pre-built command shortcuts.

Overview

JCAppleScript provides three components:

1. JCAppleScript (library) - Core AppleScript execution engine
2. AppShortcuts (library) - Registry of pre-built AppleScript commands for popular macOS apps
3. jcas-mcp (executable) - MCP (Model Context Protocol) server for AI-driven app automation

Installation

Swift Package Manager

Add JCAppleScript to your Package.swift:

dependencies: [
    .package(url: "https://github.com/johnnyclem/JCAppleScript.git", from: "2.0.0")
]

Then add the targets you need:

.target(
    name: "YourTarget",
    dependencies: [
        "JCAppleScript",     // Core engine only
        "AppShortcuts",      // App command registry
    ]
)

Quick Start

Using the Core Engine

import JCAppleScript

let engine = AppleScriptEngine.shared

// Execute raw AppleScript
let result = try engine.execute("""
    tell application "Finder"
        display dialog "Hello from Swift!"
    end tell
""")

// Send a command to an application
let output = try engine.tell(application: "Music", command: "play")

// Execute a script file with variable substitution
let fileResult = try engine.executeFile(at: "/path/to/script.scpt", variables: ["Alice", "Hello!"])

// Execute JavaScript for Automation (JXA)
let jxa = try engine.execute("Application('Music').play()", language: .javaScript)

// Check syntax without executing
try engine.checkSyntax("tell application \"Finder\" to activate")

// All execution APIs also have async variants
let asyncResult = try await engine.execute("return 40 + 2")

When embedding untrusted values in script source, escape them first:

let userInput = "…"
let script = "display dialog \(AppleScriptString.quoted(userInput))"

Using App Shortcuts

import AppShortcuts

let registry = AppRegistry.shared

// Execute a pre-built command
let result = try registry.executeCommand("messages.send_message", arguments: [
    "recipient": "+15551234567",
    "message": "Hello from JCAppleScript!"
])

// Discover available commands
let commands = registry.commands(forApp: "Reminders")
for cmd in commands {
    print("\(cmd.id): \(cmd.name) - \(cmd.description)")
}

// Search across all apps
let results = registry.searchCommands("send")

Using the MCP Server

The jcas-mcp executable is a Model Context Protocol server that AI assistants (Claude, GPT, etc.) can use to control macOS applications.

It is published to the official MCP registry as io.github.johnnyclem/jcas-mcp, and each GitHub release ships a prebuilt jcas-mcp.mcpb bundle (universal macOS binary) that can be installed directly in Claude Desktop via Settings → Extensions.

Setup with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claudedesktopconfig.json):

{
  "mcpServers": {
    "applescript": {
      "command": "/path/to/jcas-mcp"
    }
  }
}

Build the server:

swift build -c release
# Binary at: .build/release/jcas-mcp

Available MCP Tools

Shortened. The full README is on GitHub.