Skip to content
Back to search

applescript-mcp

A macOS AppleScript MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/joshrutkowski--applescript-mcp/badge.svg)](/listings/joshrutkowski--applescript-mcp)

HTML

<a href="/listings/joshrutkowski--applescript-mcp"><img src="/api/listings/joshrutkowski--applescript-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Install dependencies
npm install

# Build the server
npm run build

# Launch MCP Inspector
# See: https://modelcontextprotocol.io/docs/tools/inspector
npx @modelcontextprotocol/inspector node path/to/server/index.js args...

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 469 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # applescript-mcp MCP Server
  2. A Model Context Protocol server that enables LLM applications to interact with macOS through AppleScript.
  3. This server provides a standardized interface for AI applications to control system functions, manage files, handle notifications, and more.
  4. [![Node.js CI](https://github.com/joshrutkowski/applescript-mcp/actions/workflows/node.js.yml/badge.svg)](https://github.com/joshrutkowski/applescript-mcp/actions/workflows/node.js.yml)
  5. <a href="https://glama.ai/mcp/servers/0t5gydjcqw"><img width="380" height="200" src="https://glama.ai/mcp/servers/0t5gydjcqw/badge" alt="applescript-mcp MCP server" /></a>
  6. ## Features
  7. - 🗓️ Calendar management (events, reminders)
  8. - 📋 Clipboard operations
  9. - 🔍 Finder integration
  10. - 🔔 System notifications
  11. - ⚙️ System controls (volume, dark mode, apps)
  12. - 📟 iTerm terminal integration
  13. - 📬 Mail (create new email, list emails, get email)
  14. - 🔄 Shortcuts automation
  15. - 💬 Messages (list chats, get messages, search messages, send a message)
  16. - 🗒️ Notes (create formatted notes, list notes, search notes)
  17. - 📄 Pages (create documents)
  18. ### Planned Features
  19. - 🧭 Safari (open in Safari, save page content, get selected page/tab)
  20. - ✅ Reminders (create, get)
  21. ## Prerequisites
  22. - macOS 10.15 or later
  23. - Node.js 18 or later
  24. ## Available Categories
  25. ### Calendar
  26. | Command | Description | Parameters |
  27. | ------- | --------------------- | --------------------------------------------------- |
  28. | `add` | Create calendar event | `title`, `startDate`, `endDate`, `calendar` (optional) |
  29. | `list` | List today's events | None |
  30. #### Examples
  31. ```
  32. // Create a new calendar event
  33. Create a calendar event titled "Team Meeting" starting tomorrow at 2pm for 1 hour
  34. // List today's events
  35. What events do I have scheduled for today?
  36. ```
  37. ### Clipboard
  38. | Command | Description | Parameters |
  39. | ----------------- | ---------------------- | ---------- |
  40. | `set_clipboard` | Copy to clipboard | `content` |
  41. | `get_clipboard` | Get clipboard contents | None |
  42. | `clear_clipboard` | Clear clipboard | None |
  43. #### Examples
  44. ```
  45. // Copy text to clipboard
  46. Copy "Remember to buy groceries" to my clipboard
  47. // Get clipboard contents
  48. What's currently in my clipboard?
  49. // Clear clipboard
  50. Clear my clipboard
  51. ```
  52. ### Finder
  53. | Command | Description | Parameters |
  54. | -------------------- | ------------------ | ------------------------------ |
  55. | `get_selected_files` | Get selected files | None |
  56. | `search_files` | Search for files | `query`, `location` (optional) |
  57. | `quick_look` | Preview file | `path` |
  58. #### Examples
  59. ```
  60. // Get selected files in Finder
  61. What files do I currently have selected in Finder?
  62. // Search for files
  63. Find all PDF files in my Documents folder
  64. // Preview a file
  65. Show me a preview of ~/Documents/report.pdf
  66. ```
  67. ### Notifications
  68. > Note: Sending notification requires that you enable notifications in System Settings > Notifications > Script Editor.
  69. | Command | Description | Parameters |
  70. | ----------------------- | ----------------- | -------------------------------------- |
  71. | `send_notification` | Show notification | `title`, `message`, `sound` (optional) |
  72. | `toggle_do_not_disturb` | Toggle DND mode | None |
  73. #### Examples
  74. ```
  75. // Send a notification
  76. Send me a notification with the title "Reminder" and message "Time to take a break"
  77. // Toggle Do Not Disturb
  78. Turn on Do Not Disturb mode
  79. ```
  80. ### System
  81. | Command | Description | Parameters |
  82. | ------------------- | ----------------- | -------------------------- |
  83. | `volume` | Set system volume | `level` (0-100) |
  84. | `get_frontmost_app` | Get active app | None |
  85. | `launch_app` | Open application | `name` |
  86. | `quit_app` | Close application | `name`, `force` (optional) |
  87. | `toggle_dark_mode` | Toggle dark mode | None |
  88. #### Examples
  89. ```
  90. // Set system volume
  91. Set my Mac's volume to 50%
  92. // Get active application
  93. What app am I currently using?
  94. // Launch an application
  95. Open Safari
  96. // Quit an application
  97. Close Spotify
  98. // Toggle dark mode
  99. Switch to dark mode
  100. ```
  101. ### iTerm
  102. | Command | Description | Parameters |
  103. | ----------------- | --------------- | --------------------------------- |
  104. | `paste_clipboard` | Paste to iTerm | None |
  105. | `run` | Execute command | `command`, `newWindow` (optional) |
  106. #### Examples
  107. ```
  108. // Paste clipboard to iTerm
  109. Paste my clipboard contents into iTerm
  110. // Run a command in iTerm
  111. Run "ls -la" in iTerm
  112. // Run a command in a new iTerm window
  113. Run "top" in a new iTerm window
  114. ```
  115. ### Shortcuts
  116. | Command | Description | Parameters |
  117. | ---------------- | ------------------------------------------ | ---------------------------------------------------- |
  118. | `run_shortcut` | Run a shortcut | `name`, `input` (optional) |
  119. | `list_shortcuts` | List all available shortcuts | `limit` (optional) |
  120. #### Examples
  121. ```
  122. // List available shortcuts
  123. List all my available shortcuts
  124. // List with limit
  125. Show me my top 5 shortcuts
  126. // Run a shortcut
  127. Run my "Daily Note in Bear" shortcut
  128. // Run a shortcut with input
  129. Run my "Add to-do" shortcut with input "Buy groceries"
  130. ```
  131. ### Mail
  132. | Command | Description | Parameters |
  133. | ------------- | -------------------------------- | --------------------------------------------------------- |
  134. | `create_email`| Create a new email in Mail.app | `recipient`, `subject`, `body` |
  135. | `list_emails` | List emails from a mailbox | `mailbox` (optional), `count` (optional), `unreadOnly` (optional) |
  136. | `get_email` | Get a specific email by search | `subject` (optional), `sender` (optional), `dateReceived` (optional), `mailbox` (optional), `account` (optional), `unreadOnly` (optional), `includeBody` (optional) |
  137. #### Examples
  138. ```
  139. // Create a new email
  140. Compose an email to john@example.com with subject "Meeting Tomorrow" and body "Hi John, Can we meet tomorrow at 2pm?"
  141. // List emails
  142. Show me my 10 most recent unread emails
  143. // Get a specific email
  144. Find the email from sarah@example.com about "Project Update"
  145. ```
  146. ### Messages
  147. | Command | Description | Parameters |
  148. | ----------------- | -------------------------------------------- | --------------------------------------------------------- |
  149. | `list_chats` | List available iMessage and SMS chats | `includeParticipantDetails` (optional, default: false) |
  150. | `get_messages` | Get messages from the Messages app | `limit` (optional, default: 100) |
  151. | `search_messages` | Search for messages containing specific text | `searchText`, `sender` (optional), `chatId` (optional), `limit` (optional, default: 50), `daysBack` (optional, default: 30) |
  152. | `compose_message` | Open Messages app with pre-filled message or auto-send | `recipient` (required), `body` (optional), `auto` (optional, default: false) |
  153. #### Examples
  154. ```
  155. // List available chats
  156. Show me my recent message conversations
  157. // Get recent messages
  158. Show me my last 20 messages
  159. // Search messages
  160. Find messages containing "dinner plans" from John in the last week
  161. // Compose a message
  162. Send a message to 555-123-4567 saying "I'll be there in 10 minutes"
  163. ```
  164. ### Notes
  165. | Command | Description | Parameters |
  166. | ----------------- | -------------------------------------------- | --------------------------------------------------------- |
  167. | `create` | Create a note with markdown-like formatting | `title`, `content`, `format` (optional with formatting options) |
  168. | `createRawHtml` | Create a note with direct HTML content | `title`, `html` |
  169. | `list` | List notes, optionally from a specific folder| `folder` (optional) |
  170. | `get` | Get a specific note by title | `title`, `folder` (optional) |
  171. | `search` | Search for notes containing specific text | `query`, `folder` (optional), `limit` (optional, default: 5), `includeBody` (optional, default: true) |
  172. #### Examples
  173. ```
  174. // Create a new note with markdown formatting
  175. Create a note titled "Meeting Minutes" with content "# Discussion Points\n- Project timeline\n- Budget review\n- Next steps" and format headings and lists
  176. // Create a note with HTML
  177. Create a note titled "Formatted Report" with HTML content "<h1>Quarterly Report</h1><p>Sales increased by <strong>15%</strong></p>"
  178. // List notes
  179. Show me all my notes in the "Work" folder
  180. // Get a specific note
  181. Show me my note titled "Shopping List"
  182. // Search notes
  183. Find notes containing "recipe" in my "Cooking" folder
  184. ```
  185. ### Pages
  186. | Command | Description | Parameters |
  187. | ----------------- | -------------------------------------------- | --------------------------------------------------------- |
  188. | `create_document` | Create a new Pages document with plain text | `content` |
  189. #### Examples
  190. ```
  191. // Create a new Pages document
  192. Create a Pages document with the content "Project Proposal\n\nThis document outlines the scope and timeline for the upcoming project."
  193. ```
  194. ## Architecture
  195. The applescript-mcp server is built using TypeScript and follows a modular architecture:
  196. ### Core Components
  197. 1. **AppleScriptFramework** (`framework.ts`): The main server class that:
  198. - Manages MCP protocol communication
  199. - Handles tool registration and execution
  200. - Provides logging functionality
  201. - Executes AppleScript commands
  202. 2. **Categories** (`src/categories/*.ts`): Modular script collections organized by functionality:
  203. - Each category contains related scripts (e.g., calendar, system, notes)
  204. - Categories are registered with the framework in `index.ts`
  205. 3. **Types** (`src/types/index.ts`): TypeScript interfaces defining:
  206. - `ScriptDefinition`: Structure for individual scripts
  207. - `ScriptCategory`: Collection of related scripts
  208. - `LogLevel`: Standard logging levels
  209. - `FrameworkOptions`: Configuration options
  210. ### Execution Flow
  211. 1. Client sends a tool request via MCP protocol
  212. 2. Server identifies the appropriate category and script
  213. 3. Script content is generated (static or dynamically via function)
  214. 4. AppleScript is executed via macOS `osascript` command
  215. 5. Results are returned to the client
  216. ### Logging System
  217. The framework includes a comprehensive logging system that:
  218. - Logs to both stderr and MCP logging protocol
  219. - Supports multiple severity levels (debug, info, warning, error, etc.)
  220. - Provides detailed execution information for troubleshooting
  221. ## Development
  222. ### Setup
  223. ```bash
  224. # Install dependencies
  225. npm install
  226. # Build the server
  227. npm run build
  228. # Launch MCP Inspector
  229. # See: https://modelcontextprotocol.io/docs/tools/inspector
  230. npx @modelcontextprotocol/inspector node path/to/server/index.js args...
  231. ```
  232. ### Adding New Functionality
  233. #### 1. Create Category File
  234. Create `src/categories/newcategory.ts`:
  235. ```typescript
  236. import { ScriptCategory } from "../types/index.js";
  237. export const newCategory: ScriptCategory = {
  238. name: "category_name",
  239. description: "Category description",
  240. scripts: [
  241. // Scripts will go here
  242. ],
  243. };
  244. ```
  245. #### 2. Add Scripts
  246. ```typescript
  247. {
  248. name: "script_name",
  249. description: "What the script does",
  250. schema: {
  251. type: "object",
  252. properties: {
  253. paramName: {
  254. type: "string",
  255. description: "Parameter description"
  256. }
  257. },
  258. required: ["paramName"]
  259. },
  260. script: (args) => `
  261. tell application "App"
  262. // AppleScript code using ${args.paramName}
  263. end tell
  264. `
  265. }
  266. ```
  267. #### 3. Register Category
  268. Update `src/index.ts`:
  269. ```typescript
  270. import { newCategory } from "./categories/newcategory.js";
  271. // ...
  272. server.addCategory(newCategory);
  273. ```
  274. ### Advanced Script Development
  275. For more complex scripts, you can:
  276. 1. **Use dynamic script generation**:
  277. ```typescript
  278. script: (args) => {
  279. // Process arguments and build script dynamically
  280. let scriptContent = `tell application "App"\n`;
  281. if (args.condition) {
  282. scriptContent += ` // Conditional logic\n`;
  283. }
  284. scriptContent += `end tell`;
  285. return scriptContent;
  286. }
  287. ```
  288. 2. **Process complex data**:
  289. ```typescript
  290. // Example from Notes category
  291. function generateNoteHtml(args: any): string {
  292. // Process markdown-like syntax into HTML
  293. let processedContent = content;
  294. if (format.headings) {
  295. processedContent = processedContent.replace(/^# (.+)$/gm, '<h1>$1</h1>');
  296. // ...
  297. }
  298. return processedContent;
  299. }
  300. ```
  301. ## Debugging
  302. ### Using MCP Inspector
  303. The MCP Inspector provides a web interface for testing and debugging your server:
  304. ```bash
  305. npm run inspector
  306. ```
  307. ### Logging
  308. Enable debug logging by setting the environment variable:
  309. ```bash
  310. DEBUG=applescript-mcp* npm start
  311. ```
  312. ### Example configuration
  313. After running `npm run build` add the following to your `mcp.json` file:
  314. ```json
  315. {
  316. "mcpServers": {
  317. "applescript-mcp-server": {
  318. "command": "node",
  319. "args": ["/path/to/applescript-mcp/dist/index.js"]
  320. }
  321. }
  322. }
  323. ```
  324. ### Common Issues
  325. - **Permission Errors**: Check System Preferences > Security & Privacy > Privacy > Automation
  326. - **Script Failures**: Test scripts directly in Script Editor.app before integration
  327. - **Communication Issues**: Check stdio streams aren't being redirected
  328. - **Database Access**: Some features (like Messages) require Full Disk Access permission
  329. ## Resources
  330. - [AppleScript Language Guide](https://developer.apple.com/library/archive/documentation/AppleScript/Conceptual/AppleScriptLangGuide/introduction/ASLR_intro.html)
  331. - [MCP Protocol Documentation](https://modelcontextprotocol.io)
  332. - [Issue Tracker](https://github.com/joshrutkowski/applescript-mcp/issues)
  333. ## Contributing
  334. 1. Fork the repository
  335. 2. Create a feature branch
  336. 3. Commit your changes
  337. 4. Push to the branch
  338. 5. Create a Pull Request
  339. ## License
  340. MIT License - see [LICENSE](LICENSE) for details

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.