Amber Notes (ambernotes.app)

npx add-mcp 'https://mcp.ambernotes.app'

Amber Notes, o aplicativo de notas para iPhone e Mac, tem um servidor MCP remoto integrado. Esta página é para desenvolvedores e qualquer pessoa curiosa sobre como funciona: o endereço, como um aplicativo de IA faz login e é aprovado, e todas as ferramentas que ele pode chamar.

Amber Notes perguntando "Permitir que o ChatGPT use suas notas?" com uma escolha de Ler e Editar ou Somente Leitura, e botões Permitir e Não Permitir.

O endereço

https://mcp.ambernotes.app

• Transporte: MCP Streamable HTTP, respondendo com JSON. Não há stream enviado pelo servidor; os clientes enviam cada solicitação via POST.
• Versões de protocolo: 2025-11-25, 2025-06-18, 2025-03-26 e 2024-11-05.
• Nome do servidor: amber-notes. Ele envia instruções em initialize que informam ao modelo como as notas estão organizadas.

Como o acesso funciona

Existem duas formas de entrar. Ambas precisam de uma conta Amber Notes, e ambas são aprovadas pela pessoa.

Entrar com OAuth (ChatGPT, Claude e outros aplicativos)

1. Uma solicitação não autenticada recebe um 401 com um cabeçalho WWW-Authenticate apontando para os metadados do recurso protegido, no endereço acima mais /.well-known/oauth-protected-resource.
2. O cliente se registra (registro dinâmico de cliente) e inicia OAuth 2.1 com PKCE (S256). Os escopos são notes:read e notes:write.
3. Os metadados do servidor de autorização estão no endereço acima mais /.well-known/oauth-authorization-server.
4. A etapa de autorização abre ambernotes.app/connect. A pessoa faz login lá (e-mail e senha, ou Entrar com Apple), e a página mostra um número de dois dígitos. O Amber Notes no iPhone ou Mac dela pergunta "Permitir que [app] use suas notas?" e para onde o acesso vai; ela digita o número, escolhe Ler e Editar ou Somente Leitura, e então Permite. Sem um dispositivo por perto, ela pode aprovar na página com a chave de recuperação.
5. O cliente recebe um token de acesso (válido por uma hora) e um token de atualização. Os tokens só abrem este servidor.

Token de acesso (Claude Code, Codex e scripts)

No Amber Notes, em Configurações, Conectar uma IA, o Claude Code ou o Codex cria um token começando com pane_, somente leitura ou leitura e edição. Envie-o como Authorization: Bearer pane_…. O guia do Claude Code e Codex tem a configuração exata.

Configurações, Conectar uma IA: configuração guiada para cada aplicativo e tudo o que está conectado.

Toda conexão aparece no Amber Notes em Conectado, e a pessoa pode desconectá-la a qualquer momento. Cada chamada de ferramenta é executada como essa pessoa, com segurança em nível de linha, então um token só pode alcançar as notas do seu dono. As chamadas são limitadas por conta.

As notas são criptografadas de ponta a ponta, então o servidor não pode lê-las em repouso. Aprovar uma conexão dá a ela uma cópia da chave das notas, bloqueada com um segredo derivado do seu próprio token. Durante cada solicitação, o servidor desbloqueia a chave na memória, descriptografa o que a chamada precisa e a descarta quando a solicitação termina; desconectar exclui essa cópia. Notas bloqueadas ficam fora de alcance, pois sua chave vem da senha das notas. Um aplicativo de notas criptografado que ChatGPT e Claude podem usar explica a compensação.

O que acontece com as alterações

• Cada edição mantém a versão anterior. note_history as lista e restore_revision restaura uma.
• No aplicativo, a pessoa vê o que uma IA alterou, com Desfazer.
• Notas excluídas vão para Excluídas Recentemente por 30 dias e podem ser restauradas com restore_note.
• Uma conexão somente leitura só vê as ferramentas marcadas como leituras abaixo.

Ferramentas

As notas são em markdown, e a primeira linha é o título. Listas de verificação são linhas - [ ], e tabelas são tabelas markdown. Comece com get_overview ou search_notes, e leia uma nota antes de editá-la.

• get_overview (leituras). Uma visão geral das Amber Notes da pessoa: pastas com contagens, notas fixadas e as notas editadas mais recentemente.
• search_notes (leituras). Pesquisa de texto completo em títulos e corpos. Retorna notas classificadas com um trecho destacado («correspondência»). Notas bloqueadas são deixadas de fora.
• list_notes (leituras). Lista notas, das mais recentes para as mais antigas, opcionalmente em uma pasta. Use para navegar; use search_notes para encontrar algo.
• read_note (leituras). Retorna o markdown de uma nota com sua pasta, datas, versão e esboço. Para notas longas, leia um intervalo de linhas; defina line_numbers para ver onde estão os cabeçalhos.
• create_note (alterações). Cria uma nota a partir de markdown. A primeira linha se torna o título (escreva como texto simples ou '# Título').
• edit_note (alterações; pode remover ou substituir). Edições precisas: cada old_text deve corresponder à nota exatamente uma vez (copie de read_note) e é substituído por new_text. As edições são aplicadas em ordem. Falha sem alterar nada se uma não corresponder.
• append_to_note (alterações). Adiciona markdown ao final de uma nota, ou ao final (ou início) da seção sob um cabeçalho. Bom para registros, listas e diários.
• replace_note_body (alterações; pode remover ou substituir). Substitui a nota inteira por novo markdown. Use apenas para reescritas completas; prefira edit_note. A pessoa vê a alteração no Amber Notes com Desfazer, e a versão antiga permanece no histórico.
• set_checklist_item (alterações). Marca ou desmarca uma linha '- [ ] item', correspondida pelo seu texto.
• move_note (alterações). Move uma nota para outra pasta, criando a pasta se ela não existir. Use um caminho como "Trabalho/Clientes" para aninhar.
• pin_note (alterações). Fixa uma nota no topo da lista, ou a desafixa. O estado fixado aparece como pinned\ em cada listagem de notas.
• delete_note (alterações; pode remover ou substituir). Move uma nota e suas sub-notas para Excluídas Recentemente. Isso pode ser desfeito: restore_note a traz de volta dentro de 30 dias.
• restore_note (alterações). Traz uma nota (e suas sub-notas) de volta de Excluídas Recentemente.
• list_folders (leituras). Todas as pastas como caminhos como "Trabalho/Planejamento Q4", com quantas notas cada uma mostra no aplicativo.
• create_folder (alterações). Cria uma pasta; use um caminho como "Trabalho/Clientes" para aninhá-la.
• rename_folder (alterações). Renomeia uma pasta no lugar. Suas notas e sub-pastas permanecem dentro dela.
• delete_folder (alterações; pode remover ou substituir). Exclui uma pasta e suas sub-pastas. Suas notas (e as sub-notas dessas notas) vão para Excluídas Recentemente, e cada uma pode ser trazida de volta com restore_note dentro de 30 dias; as pastas em si não são restauradas.
• note_history (leituras). Versões anteriores de uma nota, das mais recentes para as mais antigas, com quem a alterou (aplicativo ou cliente de IA).
• restore_revision (alterações; pode remover ou substituir). Coloca uma versão anterior (de note_history) de volta como o corpo da nota. O corpo atual também é mantido no histórico.
• create_sub_note (alterações). Cria uma nota que vive dentro de outra nota: ela é vinculada a partir da nota pai (uma linha [Título](pane-note:id) adicionada no final, ou sob um cabeçalho) e não aparece na lista principal.
• list_files (leituras). Arquivos mantidos no Amber Notes (PDFs, planilhas, imagens…), dos mais recentes para os mais antigos, com as notas que os incorporam.
• get_file (leituras). Os detalhes de um arquivo e seu conteúdo: arquivos de texto (CSV, JSON, markdown…) como texto, imagens como imagem, PDFs e outros arquivos como recurso anexado. Arquivos acima de 8 MB só podem ser abertos no Amber Notes.
• read_table (leituras). Lê uma tabela em uma nota: suas colunas (com tipos e valores permitidos para rastreadores) e suas linhas como objetos. Use antes de registrar para usar os nomes e valores de coluna corretos.
• log_table_row (alterações; pode remover ou substituir). Adiciona uma linha a uma tabela. Em um rastreador com coluna de data, atualiza a linha dessa data se houver uma (a data padrão é hoje). Os valores são verificados contra o tipo de cada coluna: escalas devem estar no intervalo, escolhas uma das opções, Sim/Não também aceita verdadeiro/falso.
• delete_table_row (alterações; pode remover ou substituir). Remove a linha de uma data (rastreadores) ou em um índice de linha baseado em 0 de uma tabela.
• search (leituras). Pesquisa as Amber Notes da pessoa por palavras ou frases. Retorna ids e títulos de notas; leia um com fetch. Notas bloqueadas são deixadas de fora.
• fetch (leituras). Busca uma nota do Amber Notes por id (da pesquisa) como seu markdown completo, com pasta, estado fixado e hora da última edição.

search e fetch seguem o formato que o ChatGPT espera para pesquisar e ler. Cada ferramenta carrega anotações MCP (readOnlyHint, e destructiveHint onde se aplica), para que os clientes possam perguntar antes de uma alteração.

Instalar na sua ferramenta de IA

Cada uma destas adiciona o endereço acima. Na primeira vez que a ferramenta se conecta, seu navegador abre ambernotes.app/connect: faça login lá, depois aprove no seu iPhone ou Mac digitando o número que a página mostra, e escolha Ler e Editar ou Somente Leitura. Você precisa do aplicativo gratuito e de uma conta.

Claude Code

claude plugin marketplace add emilwagman/amber-notes
claude plugin install amber-notes

O plugin adiciona o servidor e uma habilidade que informa ao Claude como suas notas estão organizadas. Depois execute /mcp no Claude Code, escolha amber-notes e faça login.

Ou adicione apenas o servidor, para todos os projetos:

claude mcp add --scope user --transport http amber-notes https://mcp.ambernotes.app

Codex

codex mcp add amber_notes --url https://mcp.ambernotes.app

O Codex inicia o login imediatamente. Para entrar novamente mais tarde, execute codex mcp login amber_notes.

Gemini CLI

gemini extensions install https://github.com/emilwagman/amber-notes

Depois execute /mcp auth amber-notes no Gemini CLI para entrar.

VS Code

code --add-mcp '{"name":"amber-notes","type":"http","url":"https://mcp.ambernotes.app"}'

Na primeira vez que o VS Code inicia o servidor, ele pede que você faça login.

Incredible

1. Abra Apps e procure por Amber Notes.
2. Escolha Conectar e depois Permitir no Amber Notes.
3. De volta ao Incredible, escolha Vamos lá.

O Amber Notes mostra como um aplicativo neste computador que se chama "incredible", começando em Somente Leitura. Em uma versão mais antiga do Incredible, escolha Adicionar aqui na parte inferior de Apps (ou Adicionar outro servidor MCP), cole https://mcp.ambernotes.app, e depois Continuar e Entrar, e Adicionar servidor depois de permitir.

Com um token em vez de entrar

Qualquer uma dessas ferramentas pode usar um token de acesso. No Amber Notes, abra Configurações, Conectar uma IA, Codex, e escolha Criar Token de Acesso. O token funciona em qualquer cliente MCP; envie-o como um cabeçalho Authorization: Bearer pane_…, da forma que o guia do Claude Code e Codex mostra. Ele é mostrado apenas uma vez, então mantenha-o privado.

Conecte-o

• Conecte ChatGPT ou Claude às suas notas: adicione o endereço como um aplicativo ou conector personalizado.
• Use suas notas do Claude Code e Codex: um comando, ou algumas linhas de configuração.
• Gemini CLI, VS Code e Incredible: os passos para cada um estão acima.
• Qualquer outra coisa que fale MCP: adicione o endereço e entre quando for solicitado.

Escolhendo um aplicativo de notas para um agente? O melhor aplicativo de notas para agentes de IA define os critérios. Vindo do Apple Notes? Servidores MCP do Apple Notes comparados cobre os servidores locais para Notes em um Mac e como eles diferem deste. Servidores MCP do Obsidian comparados faz o mesmo para cofres do Obsidian.

O servidor é de código aberto. Leia-o em supabase/functions/mcp no GitHub.

Verificado contra o aplicativo em .