This MCP server exposes AppleScript capabilities to LLM clients via the Beyond Better bb-mcp-server framework. It enables safe, structured interaction with macOS applications through predefined AppleScript scripts bundled in the server (e.g., Finder operations, BBEdit integration, and other scriptable apps). By default, arbitrary script execution is disabled for safety, and a plugin system governs which tools are available. You can enable specific plugins and adjust timeouts to balance responsiveness with safety.

To use the server, configure it as an MCP server in your BB (Beyond Better) environment. The Quick Start demonstrates running the server from JSR (no installation required) by launching Deno with the bb-applescript MCP server package. The server provides a standard AppleScript toolkit (e.g., read_dictionary, check_permissions, and Finder operations) as well as BBEdit-related tools. You can run or test the server locally, or connect Claude Desktop or other clients by pointing them at the server configuration. The available tools are accessed through the MCP API, and responses are structured with clear errors and hints suitable for LLM-based interactions.

Prerequisites:

• macOS with AppleScript support
• Deno 2.5.0 or later
• A host environment capable of running MCP servers (e.g., Beyond Better BB integration, Claude Desktop, or your own client)

Option A: Run directly (no install required)

1. Ensure Deno is installed: curl -fsSL https://deno.land/install.sh | sh
2. Start using the server via JSR-like integration (as demonstrated in the README): deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-applescript-mcp-server
3. If integrating with Claude Desktop, configure via claude_desktop_config.json as shown in the README: { "mcpServers": { "applescript": { "command": "deno", "args": [ "run", "--allow-all", "--unstable-kv", "jsr:@beyondbetter/bb-applescript-mcp-server" ] } } }

Option B: Run from a local repository (development)

1. Clone the repository and navigate to the server folder: git clone https://github.com/your-username/bb-mcp-applescript.git cd bb-mcp-applescript/server
2. Copy environment template and adjust as needed: cp .env.example .env
3. Edit .env to customize transport, timeouts, and enabling scripts: MCP_TRANSPORT=stdio LOG_LEVEL=info ENABLE_ARBITRARY_SCRIPTS=false APPLESCRIPT_TIMEOUT_DEFAULT=30000 APPLESCRIPT_TIMEOUT_MAX=300000
4. Run in development mode with auto-reload or production mode: deno task dev

   or

   deno task start
5. Configure in Beyond Better as described in the README to expose the server to clients.

Notes and tips:

• The server ships with standard AppleScript plugins by default, including safe tools for read_dictionary, check_permissions, and Finder interactions. ArbitraryScript execution is disabled by default and only becomes available if ENABLE_ARBITRARY_SCRIPTS is set to true in environment/config.
• Timeouts are configurable via APPLESCRIPT_TIMEOUT_DEFAULT and APPLESCRIPT_TIMEOUT_MAX. Set values to fit your workload and to prevent long-running scripts from blocking the MCP server.
• When integrating with Claude Desktop or BB, you typically point the MCP server configuration to the deno command with the jsr package path. Ensure the path in your client configuration matches how you run the server.
• Plugins can be controlled with PLUGINS_ALLOWED_LIST and PLUGINS_BLOCKED_LIST to restrict or permit specific capabilities.
• If you plan to develop or customize AppleScript scripts, you can modify the scripts under server/src/plugins/standard.plugin/scripts and server/src/plugins/bbedit.plugin/scripts.