bb-applescript

bb-applescript-mcp-server is an MCP server that enables LLM clients to interact with macOS applications via AppleScript. It is built to safely execute predefined AppleScript scripts and also supports running custom scripts, giving you control over what actions can be performed on your Mac. Once the server is running, clients can send structured requests to trigger approved AppleScript actions or to execute user-provided AppleScript snippets through the server's interface. This allows LLM-powered workflows to automate macOS tasks, automate UI interactions, and integrate AppleScript-driven capabilities into larger AI-assisted pipelines.

To use the server, ensure it’s running on your macOS machine and accessible to your LLM client. The server exposes endpoints for listing available scripts, executing predefined scripts, and submitting custom AppleScript requests. When sending requests, keep in mind that only scripts marked as approved will be executed, and custom scripts can be restricted by policy settings. This design provides a safe bridge between LLMs and macOS automation, reducing the risk of arbitrary code execution while enabling powerful integrations.

Prerequisites:

• macOS 10.14 or higher
• Node.js installed on the system (for the provided runtime) or an environment capable of running the server.js file
• Internet access for initial setup and dependencies

Installation steps:

1. Download the release ZIP (bb-applescript-mcp-server) from the Releases page.
2. Unzip the file and locate the server package (e.g., bb-applescript-mcp-server or similar).
3. Ensure Node.js is installed on your Mac:
   • macOS: brew install node
4. Open a terminal and navigate to the server directory. Install dependencies if a package.json is provided:
   • npm install
5. Start the MCP server:
   • npm start If a direct Node.js script is provided, you can run:
   • node path/to/server.js
6. Verify the server is running by checking the console output or making a test request from your MCP client.
7. Configure the server in the MCP client as needed (see mcp_config) and ensure AppleScript permissions are granted in System Settings if prompted.

• Security: Only predefined/approved AppleScript scripts should be executed. Custom scripts can be enabled or restricted via server settings.
• AppleScript permissions: macOS may require you to grant accessibility or automation permissions for the server process. Review System Preferences > Security & Privacy > Privacy to allow the server to control your computer when prompts appear.
• Environment variables: Use APP_NAME and OS_PLATFORM (or add others as needed) to tailor logging, permissions, and behavior per environment.
• Updates: When upgrading, replace the server binary/app while keeping configuration intact to avoid reconfiguring script permissions.
• Troubleshooting: If the server fails to load scripts, verify that the scripts directory is accessible, scripts are properly formatted, and that the AppleScript engine is enabled on the host system.