Apple Notes MCP

Servidor MCP para Apple Notes com busca semântica e operações CRUD. Claude pesquisa, lê, cria, atualiza e gerencia suas Notas Apple por meio de linguagem natural.

GitHub

Documentação

apple-notes-mcp

Servidor MCP para Apple Notes com busca semântica e operações CRUD. O Claude pesquisa, lê, cria, atualiza e gerencia suas notas do Apple Notes por meio de linguagem natural.

Recursos

Busca por Chunks - Notas longas divididas em chunks para correspondência precisa
Cache de Consultas - Pesquisas repetidas 60x mais rápidas
Grafo de Conhecimento - Descoberta de tags, links e notas relacionadas
Busca Híbrida - Vetorial + busca por palavras-chave com Fusão de Ranks Recíproca
Busca Semântica - Encontre notas pelo significado, não por palavras-chave
CRUD Completo - Criar, ler, atualizar, excluir e mover notas
Indexação Incremental - Re-embedding apenas das notas alteradas
Trabalhos de Indexação em Segundo Plano - Indexação assíncrona completa/incremental com consulta de progresso
Embedding Duplo - HuggingFace local ou API OpenRouter

O que há de novo na versão 1.8.1

Filtragem de pasta list-notes mais rápida - list-notes agora consulta apenas a pasta solicitada em vez de escanear todas as notas primeiro
Correção na duplicidade de nomes de pastas - A filtragem de pastas agora agrega pastas correspondentes entre contas
Desempenho em grandes bibliotecas - A listagem com escopo de pasta é significativamente mais rápida em bibliotecas maiores de notas

Instalação

npm (recomendado)

npm install -g @disco_trooper/apple-notes-mcp
apple-notes-mcp

O assistente de configuração orienta você por:

Escolha do provedor de embedding (local ou OpenRouter)
Configuração de chaves de API, se necessário
Configuração da integração com Claude Code
Indexação das suas notas

A partir do código-fonte

git clone https://github.com/disco-trooper/apple-notes-mcp.git
cd apple-notes-mcp
bun install
bun run start

Requisitos

macOS (usa Apple Notes via JXA)
Runtime Bun
Aplicativo Apple Notes com notas

Início Rápido

Execute o comando após a instalação:

apple-notes-mcp

O assistente de configuração inicia automaticamente na primeira execução. Reinicie o Claude Code após a configuração para usar as ferramentas MCP.

Configuração

Configuração armazenada em ~/.apple-notes-mcp/.env:

Variável	Descrição	Padrão
`OPENROUTER_API_KEY`	Chave de API do OpenRouter (ativa embeddings na nuvem)	-
`EMBEDDING_MODEL`	Nome do modelo (local ou OpenRouter)	`Xenova/multilingual-e5-small`
`EMBEDDING_DIMS`	Dimensões do embedding	`4096`
`READONLY_MODE`	Bloquear todas as operações de escrita	`false`
`INDEX_TTL`	Intervalo de atualização automática na busca em segundos (desativado quando não definido)	-
`SEARCH_REFRESH_TIMEOUT_MS`	Tempo máximo que a busca espera pela atualização antes de usar o índice obsoleto	`2000`
`INDEX_JOB_RETENTION_SECONDS`	Quanto tempo trabalhos de indexação concluídos/com falha permanecem consultáveis	`3600`
`EMBEDDING_BATCH_SIZE`	Tamanho do lote para geração de embeddings	`50`
`DEBUG`	Ativar registro de depuração	`false`

Política de Atualização Automática na Busca

search-notes não força atualização a cada solicitação.
Se INDEX_TTL não estiver definido, a atualização automática está desativada e a busca usa o índice atual.
Se INDEX_TTL estiver definido, a atualização é executada somente após expirar o TTL.
Se a atualização falhar ou levar mais que SEARCH_REFRESH_TIMEOUT_MS, a busca recorre aos resultados do índice obsoleto em vez de expirar.

Para reconfigurar:

apple-notes-mcp setup
# or from source:
bun run setup

Provedores de Embedding

Local (padrão): Usa HuggingFace Transformers com Xenova/multilingual-e5-small. Gratuito, roda localmente, download de ~200MB.

OpenRouter: Usa API em nuvem. Rápido, não requer recursos locais, precisa de chave de API em openrouter.ai.

Consulte docs/models.md para comparação de modelos.

Ferramentas

Busca e Descoberta

`search-notes`

Busca híbrida vetorial + texto completo.

query: "meeting notes from last week"
folder: "Work"           # optional, filter by folder
limit: 10                # default: 20
mode: "hybrid"           # hybrid, keyword, or semantic
include_content: false   # include full content vs preview

`list-notes`

Lista notas com ordenação e filtros. Sem parâmetros, mostra estatísticas do índice.

sort_by: "modified"      # created, modified, or title (default: modified)
order: "desc"            # asc or desc (default: desc)
limit: 10                # max notes to return (1-100)
folder: "Work"           # filter by folder (case-insensitive)

Quando folder é fornecido, o servidor busca apenas as pastas correspondentes no Apple Notes. Isso mantém solicitações com escopo de pasta rápidas, mesmo quando sua biblioteca tem centenas de notas.

Exemplos:

Obter as 5 notas mais recentes: { sort_by: "created", order: "desc", limit: 5 }
Modificadas recentemente: { sort_by: "modified", limit: 10 }
Ordem alfabética na pasta: { sort_by: "title", order: "asc", folder: "Projects" }

`list-folders`

Lista todas as pastas do Apple Notes.

`get-note`

Obtém o conteúdo de uma nota pelo título.

title: "My Note"          # or "Work/My Note" for disambiguation
include_html: false       # include raw HTML (default: false)

`get-tables`

Extrai dados estruturados de tabela de uma nota.

title: "My Note"

Retorna:

{
  "tableCount": 2,
  "tables": [{
    "index": 0,
    "rows": [["Header1", "Header2"], ["Val1", "Val2"]],
    "formatting": [[{"bold": true}, {"bold": true}], ...]
  }]
}

Indexação

`index-notes`

Indexa notas para busca semântica.

mode: "incremental"       # incremental (default) or full
force: false              # force reindex even if TTL hasn't expired
background: false         # optional; defaults to false (synchronous mode)

Use mode: "full" para criar o índice de chunks e melhorar a busca em notas longas. A primeira indexação completa demora mais, pois gera chunks, mas as pesquisas subsequentes são rápidas.

Para bibliotecas grandes, prefira indexação em segundo plano:

`start-index-job`

mode: "full"               # full or incremental

Retorna um snapshot do trabalho com id, status e progress. Atualizações de progresso em etapas menores nas fases de busca, embedding e persistência.

`get-index-job`

job_id: "<job-id>"

Consulte até que o status seja completed, failed ou cancelled. Você pode ver cancelling como um status transitório.

`list-index-jobs`

limit: 10                  # optional, 1-50

`cancel-index-job`

job_id: "<job-id>"

Solicita cancelamento com melhor esforço de um trabalho em execução. O cancelamento é cooperativo:

Uma etapa longa deve atingir um ponto de verificação de cancelamento.
Trabalho parcial pode permanecer.
Inicie um novo trabalho depois que o atual atingir cancelled.

`reindex-note`

Re-indexa uma única nota após edições manuais.

title: "My Note"

Operações CRUD

`create-note`

Cria uma nota no Apple Notes.

title: "New Note"
content: "# Heading\n\nMarkdown content..."
folder: "Work"            # optional, defaults to Notes

Após criar, atualizar, excluir ou mover, o servidor sincroniza automaticamente os índices vetorial e de chunks em modo de melhor esforço. Se a sincronização falhar parcialmente, a resposta da ferramenta inclui um index sync warning. Execute reindex-note ou index-notes.

`update-note`

Atualiza uma nota existente.

title: "My Note"
content: "Updated markdown content..."
reindex: true             # re-embed after update (default: true)

`delete-note`

Exclui uma nota (requer confirmação).

title: "My Note"
confirm: true             # must be true to delete

`move-note`

Move uma nota para outra pasta.

title: "My Note"
folder: "Archive"

`batch-delete`

Exclui várias notas de uma vez.

titles: ["Note 1", "Note 2"]  # OR folder: "Old Project"
confirm: true                 # required for safety

`batch-move`

Move várias notas para uma pasta de destino.

titles: ["Note 1", "Note 2"]  # OR sourceFolder: "Old"
targetFolder: "Archive"       # required

Gerenciamento de Índice

`purge-index`

Limpa todos os dados indexados. Use ao trocar os modelos de embedding ou para corrigir um índice corrompido.

confirm: true   # required for safety

Após a limpeza, execute index-notes para reconstruir.

Grafo de Conhecimento

`list-tags`

Lista todas as tags com contagens de ocorrência.

`search-by-tag`

Encontra notas com uma tag específica.

tag: "project"
folder: "Work"    # optional
limit: 20         # default: 20

`related-notes`

Encontra notas relacionadas a uma nota de origem.

title: "My Note"
types: ["tag", "link", "similar"]  # default: all
limit: 10                          # default: 10

`export-graph`

Exporta o grafo de conhecimento para visualização.

format: "json"     # json or graphml
folder: "Work"     # optional filter

Formatos Suportados:

json - Para visualização personalizada (D3.js, aplicativos web)
graphml - Para ferramentas profissionais (Gephi, yEd, Cytoscape)

Configuração do Claude Code

Automático (recomendado)

O assistente de configuração adiciona automaticamente apple-notes-mcp ao Claude Code. Execute apple-notes-mcp após a instalação.

Manual

Adicione em ~/.claude.json:

Para instalação via npm:

{
  "mcpServers": {
    "apple-notes": {
      "command": "apple-notes-mcp",
      "args": [],
      "env": {}
    }
  }
}

Para instalação a partir do código-fonte:

{
  "mcpServers": {
    "apple-notes": {
      "command": "bun",
      "args": ["run", "/path/to/apple-notes-mcp/src/index.ts"],
      "env": {}
    }
  }
}

Exemplos de Uso

Após a configuração, use linguagem natural com o Claude:

"Pesquise minhas notas por ideias de projeto"
"Crie uma nota chamada 'Notas de Reunião' na pasta Trabalho"
"O que está na minha nota sobre planos de férias?"
"Mova a nota 'Projeto Antigo' para Arquivo"
"Indexe minhas notas" (após adicionar notas no Apple Notes)

Solução de Problemas

"Nota não encontrada"

Use o formato de caminho completo Folder/Note Title quando múltiplas notas tiverem o mesmo nome.

Primeira busca lenta

Os embeddings locais baixam o modelo no primeiro uso (~200MB). As buscas subsequentes são rápidas.

"READONLY_MODE está habilitado"

Defina READONLY_MODE=false em .env para habilitar operações de escrita.

Notas ausentes na busca

Execute index-notes para atualizar o índice de busca. Use mode: full se a versão incremental não capturar mudanças.

"Conta iCloud indisponível" / `Can't get account "iCloud"`

Este erro vem de uma implementação diferente do Apple Notes MCP que usa a ferramenta search_notes e o argumento Keywords.

Este projeto usa:

ferramenta: search-notes
argumento: query

Se seu cliente chamar search_notes com Keywords, aponte sua configuração MCP para apple-notes-mcp e reinicie o cliente.

Erros JXA

Garanta que o Apple Notes esteja em execução e contenha notas. Conceda permissões de automação quando solicitado.

"Erro de análise JSON: Identificador inesperado undefined"

Isso geralmente significa que o processo de indexação ficou sem memória. Tente:

Feche outros aplicativos para liberar memória
Defina EMBEDDING_BATCH_SIZE=25 em .env para reduzir o uso de memória
Reinicie o aplicativo Apple Notes
Execute index-notes novamente

Notas ignoradas durante a indexação

Algumas notas podem ser ignoradas se estiverem:

Bloqueadas - Desbloqueie-as no Apple Notes se quiser que sejam indexadas
Sincronizando - Aguarde a sincronização do iCloud e reindexe
Corrompidas - Tente copiar o conteúdo para uma nova nota e excluir a antiga

O indexador reportará quais notas foram ignoradas e continuará com as demais.

Desenvolvimento

# Type check
bun run check

# Run tests
bun run test

# Run with coverage
bun run test:coverage

# Run with debug logging
DEBUG=true bun run start

# Watch mode
bun run dev

Contribuições

PRs são bem-vindos! Por favor:

Execute bun run check antes de enviar
Adicione testes para novas funcionalidades
Atualize a documentação conforme necessário

Licença

MIT