macOS Automator

Execute scripts AppleScript e JXA para automatizar tarefas no macOS.

Documentação

macOS Automator MCP 🤖 — Dê ao seu agente um Mac para operar

macOS Automator MCP é um servidor do Model Context Protocol que permite que clientes MCP descubram e executem AppleScript ou JavaScript para Automação (JXA). Ele é destinado a agentes que precisam controlar aplicativos macOS, inspecionar o sistema ou reutilizar scripts de uma base de conhecimento integrada.

Instalação

Você precisa de macOS e Node.js 24 ou mais recente. Adicione o servidor à configuração do seu cliente MCP; npx baixa a versão npm atual quando o cliente o inicia.

{
  "mcpServers": {
    "macos_automator": {
      "command": "npx",
      "args": ["-y", "--package", "@steipete/macos-automator-mcp", "macos-automator-mcp"]
    }
  }
}

Se o seu cliente tiver um campo de pacote separado, use @steipete/macos-automator-mcp sem @latest.

Início rápido

Reinicie o seu cliente MCP após adicionar a configuração. Primeiro, peça para ele chamar get_scripting_tips com uma pequena busca:

{
  "search_term": "Safari front tab URL",
  "limit": 3
}

Em seguida, verifique a execução do script com um script inline somente leitura por meio de execute_script:

{
  "script_content": "return \"Hello from macOS Automator\""
}

O resultado é Hello from macOS Automator. Chamadas que controlam aplicativos ou a interface do usuário podem solicitar permissões do macOS.

Ferramentas

Ferramenta	Finalidade
`get_scripting_tips`	Listar categorias da base de conhecimento ou buscar dicas de AppleScript e JXA.
`execute_script`	Executar um script inline, arquivo de script ou ID de script da base de conhecimento.

Use get_scripting_tips antes de escrever um script do zero. Um ID executável retornado pode ser passado para execute_script como kb_script_id; scripts com espaços reservados aceitam input_data nomeados ou arguments posicionais.

execute_script executa com os privilégios do processo que hospeda o servidor MCP. Execute apenas scripts em que você confia e inspecione scripts gerados antes de permitir ações destrutivas. Consulte a referência de ferramentas para cada opção de entrada e resposta.

Permissões

O aplicativo que inicia o servidor MCP—como Terminal, um editor ou um cliente MCP de desktop—é o dono das permissões de privacidade do macOS:

Conceda acesso de Automação quando os scripts controlarem Finder, Safari, Mail ou outro aplicativo.
Conceda acesso de Acessibilidade quando os scripts usarem System Events para cliques, teclas, menus ou outros scripts de interface do usuário.

O macOS pode mostrar um prompt de primeiro uso para cada aplicativo de destino. O servidor não pode conceder essas permissões por conta própria. Consulte configuração e permissões para configuração e códigos de erro comuns.

Base de conhecimento

O pacote inclui centenas de dicas de AppleScript e JXA cobrindo tarefas do sistema, arquivos, navegadores, terminais, aplicativos de produtividade, ferramentas de desenvolvedor e automação de interface do usuário. Pesquise por palavra-chave ou categoria e execute um resultado pelo seu ID executável.

Uma base de conhecimento local pode adicionar ou substituir dicas incluídas sem alterar o pacote. Ela usa como padrão ~/.macos-automator/knowledge_base; consulte configuração e permissões para seu layout e regras de substituição.

Configuração

Variável	Valores	Padrão
`LOG_LEVEL`	`DEBUG`, `INFO`, `WARN`, `ERROR`	`INFO`
`KB_PARSING`	`lazy`, `eager`	`lazy`
`LOCAL_KB_PATH`	Caminho absoluto para uma base de conhecimento personalizada	`~/.macos-automator/knowledge_base`

lazy carrega a base de conhecimento no primeiro uso; eager a carrega na inicialização do servidor. Mais detalhes estão em configuração e permissões.

Solução de problemas

Erros de permissão como -1743 ou -10004 geralmente significam que o aplicativo host precisa de acesso de Automação ou Acessibilidade.
Erros de sintaxe de script são mais fáceis de isolar com include_executed_script_in_output e include_substitution_logs, e depois reproduzir no Script Editor.
Use um caminho POSIX absoluto com script_path e aumente timeout_seconds para scripts que legitimamente precisam de mais de 60 segundos.
JXA normalmente funciona melhor com output_format_mode: "direct"; o modo padrão auto o seleciona para JXA.

Consulte Depurando AppleScript e JXA para um guia de diagnóstico mais longo.

Desenvolvimento

pnpm install
pnpm run build
pnpm test
pnpm run lint
pnpm run validate

O repositório usa pnpm 11 e Node.js 24. O guia de desenvolvimento cobre a configuração do servidor local e contribuições para a base de conhecimento.

Comunidade

Relate bugs e proponha scripts em GitHub Issues.

Licença

MIT