intents-mcp

Os App Intents do seu Mac (Lembretes, Calendário, Notas…) como ferramentas MCP via Atalhos. Apenas APIs públicas.

GitHub
1
Experimente este MCPPatrocinado

Documentação

intents-mcp

Seu Mac já vem com mais de mil ações de apps. O intents-mcp entrega as que você escolher para o Claude Code, Codex ou qualquer cliente MCP, por meio de Atalhos, usando apenas APIs públicas.

https://github.com/user-attachments/assets/3db14186-e1c6-4724-80da-f9aced0f1fb5

$ intents-mcp census
This Mac declares 1,304 App Intents actions (1,249 unique)
in 224 metadata files, across 91 apps and system components.

  discoverable in Shortcuts  945
  simple tier                 47  background, plain inputs, returns output
  need an entity (a note…)   657  not supported yet
  …

Saída real do Mac do autor (macOS 27.0, 2026-09-26). Execute intents-mcp census para obter a sua.

Os apps descrevem suas ações para Siri e Atalhos nos metadados do App Intents. O intents-mcp lê esses metadados, permite que você escolha quais ações um agente pode usar, envolve cada uma em um Atalho assinado e pequeno, e os serve como ferramentas MCP via stdio. Quando o agente chama uma ferramenta, o Atalho executa a ação do app, e o intents-mcp lê o resultado de volta onde for possível:

> Add a reminder to call the dentist tomorrow at 10.
reminders_add → {"ok": true, "output": "Call the dentist", "verified": true,
                 "detail": "read back through Shortcuts: due 26 Sep 2026 at 10:00"}

O que funciona hoje

Ferramentas verificadas em execuções reais (macOS 27.0, Claude Code 2.1 e Codex 0.157):

FerramentaAppLeitura de volta
reminders.addLembretessim (título, data de vencimento)
calendar.create-eventCalendáriosim (título, início)
notes.createNotasnão
Ferramentas de Escrita: Resumir, RevisarFerramentas de Escritanão

Qualquer ação no nível simples (executa em segundo plano, entradas de texto/número/data/escolha simples, retorna saída) pode ser habilitada a partir de seus metadados. Essas ferramentas são marcadas como ainda não verificadas em uma execução real. Em testes, 2 de 3 funcionaram na primeira vez. A terceira (Notas "Criar Pasta") nunca terminou e foi desabilitada, então verifique uma nova ferramenta antes de confiar nela.

Instalação

brew install VladUZH/tap/intents-mcp     # prebuilt for Apple silicon; no dependencies

Macs Intel compilam a partir do código-fonte, o que requer Xcode.

Ainda não tem Homebrew? O instalador pede sua senha, depois espera RETURN, e pode ficar em silêncio por alguns minutos enquanto baixa. Isso é normal. Se você já tem Homebrew, execute brew update primeiro.

No macOS 27, isso requer um Homebrew atual (7.0 ou posterior); versões mais antigas compilam a partir do código-fonte e pedem Xcode 27. Ou a partir de um clone: swift build -c release e use .build/release/intents-mcp. Requer macOS 26 ou posterior (testado no 27.0) e o comando shortcuts, que acompanha o macOS.

Configuração (cerca de um minuto por ferramenta)

intents-mcp census                       # what your Mac has
intents-mcp list --tier simple           # checked tools first, then actions from metadata
intents-mcp enable reminders.add calendar.create-event
claude mcp add --scope user mac -- intents-mcp serve   # Claude Code, in every folder
codex mcp add mac -- intents-mcp serve                  # Codex

Os passos manuais, honestamente:

  1. enable abre cada wrapper em Atalhos. Clique em Adicionar Atalho uma vez. Atalhos não tem uma forma pública de adicionar um atalho sem esse clique.
  2. Na primeira vez que uma ferramenta é executada, Atalhos pode pedir permissão. Escolha Sempre Permitir. Em testes, pediu sempre que dados iam para outro app (Notas, CotEditor, MacWhisper), e na maioria das vezes não pediu para Lembretes e Calendário. Pode pedir novamente após você atualizar um wrapper, porque um wrapper atualizado é um novo atalho.

Ferramentas que leem o resultado de volta precisam de um segundo clique em Adicionar Atalho: Lembretes e Calendário adicionam cada um um pequeno auxiliar de leitura ("intents-mcp verify.reminders" e "intents-mcp verify.calendar"), compartilhado por todas as ferramentas desse app. Pule isso e essas ferramentas ainda funcionam, mas relatam "não verificado".

O Claude Code detecta ferramentas habilitadas ou desabilitadas em uma sessão em execução; outros clientes (por exemplo, Codex) podem precisar de uma reinicialização.

Privacidade e segurança

  • Roda no seu Mac. Apenas APIs públicas. Ele lê arquivos de metadados de apps, cria atalhos, e os executa com o comando shortcuts da Apple. Sem frameworks privados, sem mudanças em SIP ou AMFI, sem cliques via Accessibility.
  • A assinatura envolve a Apple. shortcuts sign usa sua conta iCloud, e a Apple recebe uma cópia de cada wrapper para validação (o guia de Atalhos da Apple diz isso). Um wrapper assinado também carrega a identidade de assinatura da sua Conta Apple (um identificador de conta e endereço de e-mail e número de telefone com hash), então o intents-mcp exclui o arquivo assinado assim que vê o atalho na sua biblioteca (após enable, ou na próxima enable, doctor, serve ou chamada dessa ferramenta). Não compartilhe arquivos .shortcut assinados. Atalhos adicionados ficam na sua biblioteca de Atalhos, que sincroniza via iCloud.
  • Você escolhe cada ferramenta. Nada é exposto até você enable. Ações cujos nomes ou descrições sugerem excluir, enviar, comprar ou compartilhar são sinalizadas e precisam de --allow-risky (uma lista de palavras ampla, então algumas inofensivas também são sinalizadas). Os agentes as veem marcadas como destructiveHint.
  • Sem telemetria, sem rede própria. O servidor MCP fala apenas com o cliente que o iniciou, via stdio.
  • Cada chamada é registrada localmente (intents-mcp log): ferramenta, hora, duração, sucesso, e se foi verificada, gravada quando a chamada começa e quando termina, então uma chamada interrompida ainda aparece. Argumentos e resultados não são registrados.
  • Resultados são lidos de volta onde existe uma ação de leitura: o auxiliar encontra o item com o título recém-usado e verifica se foi criado durante a chamada. (Se o app que executa seu agente já tem acesso total a Lembretes ou Calendário, isso é feito com EventKit em vez disso; veja PRIVACY.md.) Um item mais antigo com o mesmo título, ou um item diferente, relata verified: false, nunca um falso sucesso.
  • Resultados incertos são ditos. Se uma execução expira ou termina sem um resultado, a ferramenta diz que a ação pode ter acontecido mesmo assim (outcomeUnknown), então os agentes verificam antes de tentar novamente. Uma chamada que nunca começou (cancelada ou sem tempo enquanto estava na fila) diz isso.

Comandos

intents-mcp census [--json]                   count the actions this Mac declares
intents-mcp list [--app <name>] [--tier simple|entity|unsupported|all] [--json]
                                              (--json: metadata actions only, with a status
                                              field; the checked tools are at the top of the
                                              text output)
intents-mcp enable <tool>... [--allow-risky]  make actions available to agents (alias or id)
intents-mcp disable <tool>...                 stop exposing them (alias or id)
intents-mcp call <tool> '<json args>'         run a tool as an agent would
intents-mcp tools                             the enabled tools
intents-mcp log [--last <n>]                  what agents called
intents-mcp doctor                            check this Mac is ready
intents-mcp serve                             MCP over stdio

Em um terminal, a saída de texto de census, list, doctor, tools, log, enable e disable aparece uma linha por vez: cerca de 40 ms de intervalo, adicionando no máximo 2 s a um comando. Saída acima de 300 linhas (como um list completo), pipes, arquivos e --json imprimem de uma vez. INTENTS_MCP_LINE_DELAY_MS define o intervalo em milissegundos: 0 desliga, e um valor maior como 120 é mais lento, para uma gravação de tela (pode então adicionar até 10 s a um comando). Em um terminal, a saída também usa algumas cores (verde para o que funciona, amarelo para o que precisa de você, vermelho para falhas). Defina NO_COLOR=1 para desligá-las; pipes, arquivos e --json nunca as recebem.

Limitações

  • Ações de entidade ainda não são suportadas, ou seja, ações que atuam em uma nota, lembrete ou lista existente. No Mac do autor, isso é 657 das 945 ações detectáveis. Um passo "Encontrar" dos Atalhos que deveria escolher uma nota uma vez correspondeu à errada em testes, então essas ficam desativadas até que possam ser correspondidas com segurança.
  • Declarado não é o mesmo que utilizável. Algumas ações declaradas são recusadas pelos Atalhos no Mac, e algumas ignoram seus nomes de parâmetros declarados. Lembretes e Calendário funcionam por meio das ações integradas dos Atalhos em vez disso.
  • A CLI não pode excluir atalhos. Após disable, exclua o wrapper no app Atalhos você mesmo.
  • O Mac deve estar acordado. Atalhos não executa enquanto está dormindo. Outro projeto relata execuções funcionando com a tela bloqueada; isso ainda não foi testado aqui.
  • Poucos apps de terceiros enviam App Intents ainda. No Mac do autor, 8 de 50 fizeram.

Como funciona

  1. Indexação. Ele lê cada Metadata.appintents/extract.actionsdata em /Applications e /System. Nenhuma permissão é necessária. Ele mapeia cada ação para o app que você conhece e a classifica em um nível.
  2. Wrapper. Cada ferramenta vira um Atalho: Entrada JSON → Obter Valor do Dicionário por argumento → a ação do app → Obter Texto → Parar e Saída. É assinado com shortcuts sign --mode people-who-know-me.
  3. Execução. shortcuts run <UUID> --input-path … --output-path …, com stdin de /dev/null e um timeout. Argumentos são verificados primeiro, porque Atalhos silenciosamente ignora chaves que não conhece.
  4. Servir. Um pequeno servidor MCP via stdio: initialize, tools/list, tools/call. Funciona com Claude Code e com Codex atual.

Licença

MIT