AppleScript MCP

Execute AppleScript no macOS

Documentação

Servidor MCP applescript-mcp

Um servidor Model Context Protocol que permite que aplicações de LLM interajam com o macOS por meio do AppleScript. Este servidor fornece uma interface padronizada para aplicações de IA controlarem funções do sistema, gerenciarem arquivos, lidarem com notificações e muito mais.

Recursos

🗓️ Gerenciamento de calendário (eventos, lembretes)
📋 Operações de área de transferência
🔍 Integração com o Finder
🔔 Notificações do sistema
⚙️ Controles do sistema (volume, modo escuro, apps)
📟 Integração com o terminal iTerm
📬 Mail (criar novo e-mail, listar e-mails, obter e-mail)
🔄 Automação de Shortcuts
💬 Messages (listar conversas, obter mensagens, pesquisar mensagens, enviar mensagem)
🗒️ Notes (criar notas formatadas, listar notas, pesquisar notas)
📄 Pages (criar documentos)

Recursos Planejados

🧭 Safari (abrir no Safari, salvar conteúdo da página, obter página/aba selecionada)
✅ Reminders (criar, obter)

Pré-requisitos

macOS 10.15 ou posterior
Node.js 18 ou posterior

Categorias Disponíveis

Calendário

Comando	Descrição	Parâmetros
`add`	Criar evento de calendário	`title`, `startDate`, `endDate`, `calendar` (opcional)
`list`	Listar eventos de hoje	Nenhum

Exemplos

// Create a new calendar event
Create a calendar event titled "Team Meeting" starting tomorrow at 2pm for 1 hour

// List today's events
What events do I have scheduled for today?

Área de Transferência

Comando	Descrição	Parâmetros
`set_clipboard`	Copiar para a área de transferência	`content`
`get_clipboard`	Obter conteúdo da área de transferência	Nenhum
`clear_clipboard`	Limpar área de transferência	Nenhum

Exemplos

// Copy text to clipboard
Copy "Remember to buy groceries" to my clipboard

// Get clipboard contents
What's currently in my clipboard?

// Clear clipboard
Clear my clipboard

Finder

Comando	Descrição	Parâmetros
`get_selected_files`	Obter arquivos selecionados	Nenhum
`search_files`	Pesquisar arquivos	`query`, `location` (opcional)
`quick_look`	Visualizar arquivo	`path`

Exemplos

// Get selected files in Finder
What files do I currently have selected in Finder?

// Search for files
Find all PDF files in my Documents folder

// Preview a file
Show me a preview of ~/Documents/report.pdf

Notificações

Nota: O envio de notificações requer que você habilite as notificações em System Settings > Notifications > Script Editor.

Comando	Descrição	Parâmetros
`send_notification`	Mostrar notificação	`title`, `message`, `sound` (opcional)
`toggle_do_not_disturb`	Alternar modo Não Perturbe	Nenhum

Exemplos

// Send a notification
Send me a notification with the title "Reminder" and message "Time to take a break"

// Toggle Do Not Disturb
Turn on Do Not Disturb mode

Sistema

Comando	Descrição	Parâmetros
`volume`	Definir volume do sistema	`level` (0-100)
`get_frontmost_app`	Obter aplicativo ativo	Nenhum
`launch_app`	Abrir aplicativo	`name`
`quit_app`	Fechar aplicativo	`name`, `force` (opcional)
`toggle_dark_mode`	Alternar modo escuro	Nenhum

Exemplos

// Set system volume
Set my Mac's volume to 50%

// Get active application
What app am I currently using?

// Launch an application
Open Safari

// Quit an application
Close Spotify

// Toggle dark mode
Switch to dark mode

iTerm

Comando	Descrição	Parâmetros
`paste_clipboard`	Colar no iTerm	Nenhum
`run`	Executar comando	`command`, `newWindow` (opcional)

Exemplos

// Paste clipboard to iTerm
Paste my clipboard contents into iTerm

// Run a command in iTerm
Run "ls -la" in iTerm

// Run a command in a new iTerm window
Run "top" in a new iTerm window

Atalhos

Comando	Descrição	Parâmetros
`run_shortcut`	Executar um atalho	`name`, `input` (opcional)
`list_shortcuts`	Listar todos os atalhos disponíveis	`limit` (opcional)

Exemplos

// List available shortcuts
List all my available shortcuts

// List with limit
Show me my top 5 shortcuts

// Run a shortcut
Run my "Daily Note in Bear" shortcut

// Run a shortcut with input
Run my "Add to-do" shortcut with input "Buy groceries"

Mail

Comando	Descrição	Parâmetros
`create_email`	Criar um novo e-mail no Mail.app	`recipient`, `subject`, `body`
`list_emails`	Listar e-mails de uma caixa de correio	`mailbox` (opcional), `count` (opcional), `unreadOnly` (opcional)
`get_email`	Obter um e-mail específico por pesquisa	`subject` (opcional), `sender` (opcional), `dateReceived` (opcional), `mailbox` (opcional), `account` (opcional), `unreadOnly` (opcional), `includeBody` (opcional)

Exemplos

// Create a new email
Compose an email to john@example.com with subject "Meeting Tomorrow" and body "Hi John, Can we meet tomorrow at 2pm?"

// List emails
Show me my 10 most recent unread emails

// Get a specific email
Find the email from sarah@example.com about "Project Update"

Messages

Comando	Descrição	Parâmetros
`list_chats`	Listar conversas iMessage e SMS disponíveis	`includeParticipantDetails` (opcional, padrão: false)
`get_messages`	Obter mensagens do app Messages	`limit` (opcional, padrão: 100)
`search_messages`	Pesquisar mensagens contendo texto específico	`searchText`, `sender` (opcional), `chatId` (opcional), `limit` (opcional, padrão: 50), `daysBack` (opcional, padrão: 30)
`compose_message`	Abrir o app Messages com mensagem pré-preenchida ou envio automático	`recipient` (obrigatório), `body` (opcional), `auto` (opcional, padrão: false)

Exemplos

// List available chats
Show me my recent message conversations

// Get recent messages
Show me my last 20 messages

// Search messages
Find messages containing "dinner plans" from John in the last week

// Compose a message
Send a message to 555-123-4567 saying "I'll be there in 10 minutes"

Notes

Comando	Descrição	Parâmetros
`create`	Criar uma nota com formatação semelhante a Markdown	`title`, `content`, `format` (opcional com opções de formatação)
`createRawHtml`	Criar uma nota com conteúdo HTML direto	`title`, `html`
`list`	Listar notas, opcionalmente de uma pasta específica	`folder` (opcional)
`get`	Obter uma nota específica pelo título	`title`, `folder` (opcional)
`search`	Pesquisar notas contendo texto específico	`query`, `folder` (opcional), `limit` (opcional, padrão: 5), `includeBody` (opcional, padrão: true)

Exemplos

// Create a new note with markdown formatting
Create a note titled "Meeting Minutes" with content "# Discussion Points\n- Project timeline\n- Budget review\n- Next steps" and format headings and lists

// Create a note with HTML
Create a note titled "Formatted Report" with HTML content "<h1>Quarterly Report</h1><p>Sales increased by <strong>15%</strong></p>"

// List notes
Show me all my notes in the "Work" folder

// Get a specific note
Show me my note titled "Shopping List"

// Search notes
Find notes containing "recipe" in my "Cooking" folder

Pages

Comando	Descrição	Parâmetros
`create_document`	Criar um novo documento Pages com texto simples	`content`

Exemplos

// Create a new Pages document
Create a Pages document with the content "Project Proposal\n\nThis document outlines the scope and timeline for the upcoming project."

Arquitetura

O servidor applescript-mcp é construído usando TypeScript e segue uma arquitetura modular:

Componentes Principais

AppleScriptFramework (framework.ts): A classe principal do servidor que:
- Gerencia a comunicação do protocolo MCP
- Lida com o registro e a execução de ferramentas
- Fornece funcionalidade de registro (logging)
- Executa comandos AppleScript
Categories (src/categories/*.ts): Coleções modulares de scripts organizadas por funcionalidade:
- Cada categoria contém scripts relacionados (ex.: calendário, sistema, notas)
- As categorias são registradas no framework em index.ts
Types (src/types/index.ts): Interfaces TypeScript que definem:
- ScriptDefinition: Estrutura para scripts individuais
- ScriptCategory: Coleção de scripts relacionados
- LogLevel: Níveis padrão de registro (logging)
- FrameworkOptions: Opções de configuração

Fluxo de Execução

O cliente envia uma solicitação de ferramenta via protocolo MCP
O servidor identifica a categoria e o script apropriados
O conteúdo do script é gerado (estaticamente ou dinamicamente via função)
O AppleScript é executado via comando osascript do macOS
Os resultados são retornados ao cliente

Sistema de Registro (Logging)

O framework inclui um sistema abrangente de registro que:

Registra tanto no stderr quanto no protocolo de registro do MCP
Suporta vários níveis de severidade (debug, info, warning, error, etc.)
Fornece informações detalhadas de execução para solução de problemas

Desenvolvimento

Configuração

# 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...

Adicionando Nova Funcionalidade

1. Criar Arquivo de Categoria

Crie src/categories/newcategory.ts:

import { ScriptCategory } from "../types/index.js";

export const newCategory: ScriptCategory = {
  name: "category_name",
  description: "Category description",
  scripts: [
    // Scripts will go here
  ],
};

2. Adicionar Scripts

{
  name: "script_name",
  description: "What the script does",
  schema: {
    type: "object",
    properties: {
      paramName: {
        type: "string",
        description: "Parameter description"
      }
    },
    required: ["paramName"]
  },
  script: (args) => `
    tell application "App"
      // AppleScript code using ${args.paramName}
    end tell
  `
}

3. Registrar Categoria

Atualize src/index.ts:

import { newCategory } from "./categories/newcategory.js";
// ...
server.addCategory(newCategory);

Desenvolvimento Avançado de Scripts

Para scripts mais complexos, você pode:

Usar geração dinâmica de scripts:

script: (args) => {
  // Process arguments and build script dynamically
  let scriptContent = `tell application "App"\n`;
  
  if (args.condition) {
    scriptContent += `  // Conditional logic\n`;
  }
  
  scriptContent += `end tell`;
  return scriptContent;
}

Processar dados complexos:

// Example from Notes category
function generateNoteHtml(args: any): string {
  // Process markdown-like syntax into HTML
  let processedContent = content;
  
  if (format.headings) {
    processedContent = processedContent.replace(/^# (.+)$/gm, '<h1>$1</h1>');
    // ...
  }
  
  return processedContent;
}

Depuração

Usando o MCP Inspector

O MCP Inspector fornece uma interface web para testar e depurar seu servidor:

npm run inspector

Registro (Logging)

Habilite o registro de depuração definindo a variável de ambiente:

DEBUG=applescript-mcp* npm start

Exemplo de configuração

Após executar npm run build, adicione o seguinte ao seu arquivo mcp.json:

{
  "mcpServers": {
    "applescript-mcp-server": {
      "command": "node",
      "args": ["/path/to/applescript-mcp/dist/index.js"]
    }
  }
}

Problemas Comuns

Erros de Permissão: Verifique System Preferences > Security & Privacy > Privacy > Automation
Falhas de Script: Teste os scripts diretamente no Script Editor.app antes da integração
Problemas de Comunicação: Verifique se os fluxos stdio não estão sendo redirecionados
Acesso ao Banco de Dados: Alguns recursos (como Messages) exigem permissão de Acesso Total ao Disco

Recursos

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça commit das suas alterações
Envie para o branch
Crie um Pull Request

Licença

Licença MIT - consulte LICENSE para detalhes