mcp-osascript

Deixe o Claude controlar seu Mac. Mova janelas, clique em menus, digite texto, leia a área de transferência, gerencie abas do navegador, tire capturas de tela, execute Atalhos — 18 ferramentas tipadas com validação de entrada e proteções de segurança.

Listado no registro oficial de MCP como io.github.m0rvayne/mcp-osascript

Início Rápido

Claude Desktop — um clique. Baixe o mcp-osascript-1.1.3.mcpb da versão mais recente e clique duas vezes nele. O Claude Desktop instala a extensão automaticamente.

Ou adicione-o ao config manualmente:

{
  "mcpServers": {
    "osascript": {
      "command": "npx",
      "args": ["-y", "mcp-osascript"]
    }
  }
}

Adicione isto ao seu config do Claude Desktop (Settings → Developer → Edit Config), reinicie o Claude, e está pronto.

{
  "mcpServers": {
    "osascript": {
      "command": "npx",
      "args": ["-y", "mcp-osascript"]
    }
  }
}

claude mcp add osascript -- npx -y mcp-osascript

git clone https://github.com/m0rvayne/mcp-osascript.git
cd mcp-osascript && npm install
# then use: "command": "node", "args": ["/path/to/mcp-osascript/server/index.js"]

Experimente Estes Prompts

Depois de instalado, peça ao Claude:

Ferramentas

18 ferramentas tipadas, cada uma com validação de entrada, classificação de erros e mensagens de erro cientes de permissões.

Menus Autocorretivos

Quando o Claude tenta clicar em um item de menu que não existe, o servidor retorna automaticamente a lista de itens disponíveis naquele nível — para que o Claude possa tentar novamente com o nome correto. Nenhum outro servidor MCP faz isso.

User:   "Click File → Export as PDF in Preview"
Claude: calls app_menu click ["File", "Export as PDF"]
Server: "Menu item 'Export as PDF' not found in 'File'.
         Available: ['New from Clipboard', 'Open...', 'Close', 'Save',
         'Duplicate', 'Rename...', 'Export...', 'Export as PDF...']"
Claude: calls app_menu click ["File", "Export as PDF..."]
Server: "Clicked: File > Export as PDF..."

Por que mcp-osascript?

As contagens de estrelas são uma medida de popularidade, não de qualidade — ambas as alternativas são anteriores a este projeto em meses. As linhas acima são o que difere na prática.

Auditorias de segurança

Quatro auditorias red-team aprovadas (agentes adversários executados contra o código-fonte, encomendadas pelo autor — não uma certificação de terceiros), a mais recente contra a v1.1.2 com três agentes paralelos cobrindo a superfície do shell, escape de AppleScript e divulgação de informações. Ela encontrou seis defeitos reais, incluindo uma ferramenta que anulava silenciosamente a lista de permissões de esquema de outra ferramenta e um slot de concorrência que podia vazar até o servidor travar. Cada descoberta foi corrigida e possui um teste de regressão. escapeAS foi verificado contra 13 candidatos de escape de string através de osascript real — nenhum escapa.

Permissões

As ferramentas funcionam em três níveis:

• Nenhuma permissão necessária — área de transferência, notificações, URLs, aplicativos, arquivos, displays, Atalhos. Funciona imediatamente.
• Automação — abas do navegador, aplicativo em primeiro plano. O macOS solicita uma vez por navegador.
• Acessibilidade — teclado, janelas, menus, ocultar/exibir. Conceda uma vez em Ajustes do Sistema → Privacidade e Segurança → Acessibilidade.
• Gravação de Tela — apenas capturas de tela. Conceda em Ajustes do Sistema → Privacidade e Segurança → Gravação de Tela.

Peça ao Claude para executar check_permissions e ele informará quais destas já estão concedidas, quais ferramentas cada uma desbloqueia e exatamente qual painel de ajustes abrir para o restante. As sondagens são somente leitura e nunca acionam um prompt de permissão.

Quando uma permissão está ausente, o servidor informa exatamente o que fazer:

"Accessibility permission required. Grant access to 'osascript'
in System Settings > Privacy & Security > Accessibility."

Testes

npm test

84 testes de integração cobrindo todas as 18 ferramentas — validação de entrada, limites de segurança (bloqueio de esquema de URL, poluição de protótipo, limites de tamanho de script), aplicação de tempo limite, tratamento de erros de permissão e regressões para cada descoberta da auditoria de segurança.

Requisitos

• macOS 13+ (Ventura ou posterior)
• Node.js 18+

Licença

MIT