Applescript BB MCP Server
BB AppleScript MCP Server
A production-ready MCP server that enables LLM clients to interact with macOS applications through AppleScript. Built using the @beyondbetter/bb-mcp-server library, this server provides safe, controlled execution of predefined scripts with optional support for arbitrary script execution.
Features
- 🔒 Safe by Default: Arbitrary script execution disabled by default
- 📦 Plugin Architecture: Modular design with task-focused plugins
- 🛠️ Standard Tools: Read dictionaries, check permissions, Finder operations
- 📝 BBEdit Integration: Create notebooks and projects
- ⏱️ Timeout Protection: Configurable timeouts with hard limits
- 📄 Structured Errors: Consistent error handling with LLM-friendly hints
- 📊 Performance: Support for both compiled and template-based scripts
Use Cases
Developer Workflows
Automate BBEdit projects, manipulate files, and integrate with development tools through AI conversations.
File Management
Organize files, set labels, retrieve selections, and manage your file system with natural language.
App Automation
Control macOS applications that support AppleScript through your AI assistant.
Plugin Management
Plugin Loading Strategy
This server uses a hybrid plugin loading approach that automatically adapts to the runtime environment:
-
JSR Mode: When running from JSR (e.g., jsr:@beyondbetter/bb-applescript-mcp-server):
- Built-in plugins (standard-tools, bbedit) are statically loaded
- User plugins can be loaded from local directories via PLUGINS_DISCOVERY_PATHS
- Allows users to extend the server with custom plugins
-
Local Mode: When running from a local directory:
- Built-in plugins are statically loaded as fallback
- Dynamic discovery enabled by default
- Hot-reload support during development
The server automatically detects which mode it's running in and configures plugin loading appropriately. No configuration is needed - it just works!
📖 For technical details, see Plugin Loading Documentation
Adding Custom Plugins
You can add your own plugins even when running from JSR:
- Create a plugin directory:
mkdir ~/my-applescript-plugins - Add your plugin files (see plugin guide)
- Set environment variable:
PLUGINS_DISCOVERY_PATHS=/path/to/your/plugins - Restart the server
Your custom plugins will be discovered and loaded alongside the built-in plugins.
Security Considerations
- 🔒 Arbitrary Scripts: Disabled by default. Only enable if you trust the LLM client.
- 📁 File System: Scripts run with server process permissions.
- 🎯 Application Control: Can control any app with granted automation permissions.
- ⏱️ Timeout Limits: Always enforced to prevent runaway scripts.
- 📝 Error Details: May contain system information. Review error output.
Server Config
{
"mcpServers": {
"bb-applescript": {
"command": "deno",
"args": [
"run",
"--allow-all",
"--unstable-kv",
"jsr:@beyondbetter/bb-applescript-mcp-server"
]
}
}
}