AppleScript MCP Server

Instructions

Implementation Reference

• src/applescript_mcp/server.py:87-137 (handler)

  Python handler for the 'applescript_execute' tool. Writes AppleScript to temp file and executes with osascript using subprocess.run, handling timeout and errors.

  @server.call_tool()
  async def handle_call_tool(
      name: str, arguments: dict[str, Any] | None
  ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
      """Handle execution of AppleScript to interact with Mac applications and data"""
      try:
          if name == "applescript_execute":
              if not arguments or "code_snippet" not in arguments:
                  raise ValueError("Missing code_snippet argument")
  
              # Get timeout parameter or use default
              timeout = arguments.get("timeout", 60)
              
              # Create temp file for the AppleScript
              with tempfile.NamedTemporaryFile(suffix='.scpt', delete=False) as temp:
                  temp_path = temp.name
                  try:
                      # Write the AppleScript to the temp file
                      temp.write(arguments["code_snippet"].encode('utf-8'))
                      temp.flush()
                      
                      # Execute the AppleScript
                      cmd = ["/usr/bin/osascript", temp_path]
                      result = subprocess.run(
                          cmd, 
                          capture_output=True, 
                          text=True, 
                          timeout=timeout
                      )
                      
                      if result.returncode != 0:
                          error_message = f"AppleScript execution failed: {result.stderr}"
                          return [types.TextContent(type="text", text=error_message)]
                      
                      return [types.TextContent(type="text", text=result.stdout)]
                  except subprocess.TimeoutExpired:
                      return [types.TextContent(type="text", text=f"AppleScript execution timed out after {timeout} seconds")]
                  except Exception as e:
                      return [types.TextContent(type="text", text=f"Error executing AppleScript: {str(e)}")]
                  finally:
                      # Clean up the temporary file
                      try:
                          os.unlink(temp_path)
                      except:
                          pass
          else:
              raise ValueError(f"Unknown tool: {name}")
  
      except Exception as e:
          return [types.TextContent(type="text", text=f"Error: {str(e)}")]

• server.js:207-239 (handler)

  JavaScript inline handler for 'applescript_execute' tool, calls executeAppleScript function with optional remote execution support.

  async ({ code_snippet, timeout = 60 }) => {
    logger.info(`Executing AppleScript with timeout ${timeout}s`);
    
    if (!code_snippet) {
      return {
        content: [{ type: 'text', text: 'Error: Missing code_snippet argument' }]
      };
    }
    
    try {
      // Inject configuration variables into the AppleScript environment if needed
      if (code_snippet.includes('{{REMOTE_HOST}}')) {
        code_snippet = code_snippet.replace(/\{\{REMOTE_HOST\}\}/g, config.remoteHost);
      }
      
      if (code_snippet.includes('{{REMOTE_PASSWORD}}')) {
        code_snippet = code_snippet.replace(/\{\{REMOTE_PASSWORD\}\}/g, config.remotePassword);
      }
      
      if (code_snippet.includes('{{REMOTE_USER}}')) {
        code_snippet = code_snippet.replace(/\{\{REMOTE_USER\}\}/g, config.remoteUser);
      }
      
      const result = await executeAppleScript(code_snippet, timeout);
      return {
        content: [{ type: 'text', text: result }]
      };
    } catch (error) {
      return {
        content: [{ type: 'text', text: `Error: ${error.message}` }]
      };
    }
  }

• src/applescript_mcp/server.py:53-86 (registration)

  Python registration of the 'applescript_execute' tool in the list_tools handler, including schema and description.

      @server.list_tools()
      async def handle_list_tools() -> list[types.Tool]:
          """List available tools"""
          return [
              types.Tool(
                  name="applescript_execute",
                  description="""Run AppleScript code to interact with Mac applications and system features. This tool can access and manipulate data in Notes, Calendar, Contacts, Messages, Mail, Finder, Safari, and other Apple applications. Common use cases include but not limited to:
  - Retrieve or create notes in Apple Notes
  - Access or add calendar events and appointments
  - List contacts or modify contact details
  - Search for and organize files using Spotlight or Finder
  - Get system information like battery status, disk space, or network details
  - Read or organize browser bookmarks or history
  - Access or send emails, messages, or other communications
  - Read, write, or manage file contents
  - Execute shell commands and capture the output
  """,
                  inputSchema={
                      "type": "object",
                      "properties": {
                          "code_snippet": {
                              "type": "string",
                              "description": """Multi-line appleScript code to execute. """
                          },
                          "timeout": {
                              "type": "integer",
                              "description": "Command execution timeout in seconds (default: 60)"
                          }
                      },
                      "required": ["code_snippet"]
                  },
              )
          ]

• server.js:200-240 (registration)

  JavaScript registration of the 'applescript_execute' tool using server.tool, with Zod schema and inline handler.

  server.tool(
    'applescript_execute',
    'Run AppleScript code to interact with Mac applications and system features. This tool can access and manipulate data in Notes, Calendar, Contacts, Messages, Mail, Finder, Safari, and other Apple applications. Common use cases include but not limited to: - Retrieve or create notes in Apple Notes - Access or add calendar events and appointments - List contacts or modify contact details - Search for and organize files using Spotlight or Finder - Get system information like battery status, disk space, or network details - Read or organize browser bookmarks or history - Access or send emails, messages, or other communications - Read, write, or manage file contents - Execute shell commands and capture the output',
    {
      code_snippet: z.string().describe('Multi-line appleScript code to execute'),
      timeout: z.number().optional().describe('Command execution timeout in seconds (default: 60)')
    },
    async ({ code_snippet, timeout = 60 }) => {
      logger.info(`Executing AppleScript with timeout ${timeout}s`);
      
      if (!code_snippet) {
        return {
          content: [{ type: 'text', text: 'Error: Missing code_snippet argument' }]
        };
      }
      
      try {
        // Inject configuration variables into the AppleScript environment if needed
        if (code_snippet.includes('{{REMOTE_HOST}}')) {
          code_snippet = code_snippet.replace(/\{\{REMOTE_HOST\}\}/g, config.remoteHost);
        }
        
        if (code_snippet.includes('{{REMOTE_PASSWORD}}')) {
          code_snippet = code_snippet.replace(/\{\{REMOTE_PASSWORD\}\}/g, config.remotePassword);
        }
        
        if (code_snippet.includes('{{REMOTE_USER}}')) {
          code_snippet = code_snippet.replace(/\{\{REMOTE_USER\}\}/g, config.remoteUser);
        }
        
        const result = await executeAppleScript(code_snippet, timeout);
        return {
          content: [{ type: 'text', text: result }]
        };
      } catch (error) {
        return {
          content: [{ type: 'text', text: `Error: ${error.message}` }]
        };
      }
    }
  );

• server.js:68-184 (helper)

  JavaScript helper function that dispatches to local or remote AppleScript execution based on config.

  async function executeAppleScript(code, timeout = 60) {
    // Check if all remote credentials are available for SSH execution
    const useRemote = config.remoteHost && config.remoteHost !== 'localhost' &&
                      config.remoteUser && config.remotePassword;
    
    if (useRemote) {
      return executeRemoteAppleScript(code, timeout);
    } else {
      return executeLocalAppleScript(code, timeout);
    }
  }
  
  async function executeLocalAppleScript(code, timeout = 60) {
    // Create a temporary file for the AppleScript
    const tempPath = path.join(os.tmpdir(), `applescript_${Date.now()}.scpt`);
    
    try {
      // Write the AppleScript to the temporary file
      fs.writeFileSync(tempPath, code);
      
      // Execute the AppleScript
      return new Promise((resolve, reject) => {
        exec(`/usr/bin/osascript "${tempPath}"`, { timeout: timeout * 1000 }, (error, stdout, stderr) => {
          // Clean up the temporary file
          try {
            fs.unlinkSync(tempPath);
          } catch (e) {
            logger.warn(`Failed to delete temporary file: ${e.message}`);
          }
          
          if (error) {
            if (error.killed) {
              resolve(`AppleScript execution timed out after ${timeout} seconds`);
            } else {
              resolve(`AppleScript execution failed: ${stderr}`);
            }
          } else {
            resolve(stdout);
          }
        });
      });
    } catch (e) {
      return `Error executing AppleScript: ${e.message}`;
    }
  }
  
  async function executeRemoteAppleScript(code, timeout = 60) {
    logger.info(`Executing AppleScript on remote host: ${config.remoteHost}`);
    
    // Create a temporary file for the AppleScript
    const localTempPath = path.join(os.tmpdir(), `applescript_${Date.now()}.scpt`);
    const remoteTempPath = `/tmp/applescript_${Date.now()}.scpt`;
    
    try {
      // Write the AppleScript to the temporary file
      fs.writeFileSync(localTempPath, code);
      
      // Initialize SSH client
      const ssh = new NodeSSH();
      
      // Connect to remote host
      try {
        await ssh.connect({
          host: config.remoteHost,
          username: config.remoteUser,
          password: config.remotePassword,
          // Useful when password auth fails and you need to try keyboard-interactive
          tryKeyboard: true,
          onKeyboardInteractive: (name, instructions, lang, prompts, finish) => {
            if (prompts.length > 0 && prompts[0].prompt.toLowerCase().includes('password')) {
              finish([config.remotePassword]);
            }
          }
        });
        
        logger.info('SSH connection established successfully');
        
        // Upload the AppleScript file
        await ssh.putFile(localTempPath, remoteTempPath);
        
        // Execute the AppleScript on the remote machine
        const result = await ssh.execCommand(`/usr/bin/osascript "${remoteTempPath}"`, {
          timeout: timeout * 1000
        });
        
        // Clean up the remote file
        await ssh.execCommand(`rm -f "${remoteTempPath}"`);
        
        // Clean up the local file
        try {
          fs.unlinkSync(localTempPath);
        } catch (e) {
          logger.warn(`Failed to delete local temporary file: ${e.message}`);
        }
        
        // Disconnect from the remote host
        ssh.dispose();
        
        if (result.code !== 0) {
          return `Remote AppleScript execution failed: ${result.stderr}`;
        }
        
        return result.stdout;
      } catch (sshError) {
        // Clean up the local file on error
        try {
          fs.unlinkSync(localTempPath);
        } catch (e) {
          logger.warn(`Failed to delete local temporary file: ${e.message}`);
        }
        
        return `SSH error: ${sshError.message}`;
      }
    } catch (e) {
      return `Error executing remote AppleScript: ${e.message}`;
    }
  }