onenote-mcp

In English: an MCP server that lets Claude (Claude Code, Claude Desktop or any MCP client) read, create and edit OneNote pages of a personal Microsoft account through Microsoft Graph, restricted to an allowlist of sections and with no delete operation. Docs are in Brazilian Portuguese; commands and config keys are the same in any language.

Servidor MCP que deixa o Claude ler, criar e editar páginas do OneNote de uma conta pessoal da Microsoft (Outlook.com, Live), pelo Microsoft Graph. Ele só enxerga as seções de uma lista permitida que você escreve no config.toml e não tem nenhuma função de apagar.

O conteúdo das páginas vai e volta num formato próprio, o ONMD (OneNote + MD, "markdown do OneNote"): markdown comum mais o que é do OneNote (cores, etiquetas, caixas de tarefa, tabelas com fundo, destaques, colunas, imagens e anexos). Arquivo nesse formato usa a extensão .onmd.

Sumário

1. O que o Claude ganha (13 tools)

2. Requisitos

3. Passo 1: registrar o app na Microsoft

4. Passo 2: instalar

5. Passo 3: configurar

6. Passo 4: login e conferência

7. Passo 5: registrar no Claude

8. Como usar

9. Formato ONMD

10. Segurança

11. Limites conhecidos

12. Solução de problemas

13. Testes, licença e créditos

Related MCP server: MCP OneNote Server

O que o Claude ganha (13 tools)

Toda escrita devolve avisos[] (o que o OneNote vai mudar ou perder). O "antes" de cada edição fica num diário local (%LOCALAPPDATA%\onenote-mcp\historico\<pagina>.jsonl), porque o Graph não guarda histórico de versões.

Requisitos

• Windows (é onde foi feito e testado). O token fica num cache cifrado pelo msal-extensions: DPAPI no Windows; no macOS e no Linux a biblioteca usa Keychain e libsecret, mas isso não foi testado aqui. Nos exemplos abaixo, em macOS/Linux troque .venv\Scripts\python.exe por .venv/bin/python.

• Python 3.12 ou mais novo.

• uv ou o pip que vem com o Python.

• Conta pessoal da Microsoft com OneNote (conta corporativa/escolar não foi testada: o login usa o endereço consumers, só de contas pessoais).

• Conta Azure gratuita para registrar o app (passo 1 explica por quê).

• Claude Code, Claude Desktop ou outro cliente MCP que rode servidor por stdio.

Passo 1: registrar o app na Microsoft (uma vez)

O servidor faz login em seu nome (login delegado). Para isso a Microsoft exige um "app registrado", que dá um ID do aplicativo (cliente). Não há segredo nem senha de app: é um cliente público.

Por que precisa de conta Azure: uma conta pessoal não consegue mais registrar app "fora de um diretório" (o portal diz que a capacidade foi preterida e manda se inscrever no Azure; conferido em outubro de 2026). A conta Azure gratuita basta. A inscrição pode pedir cartão de crédito só para verificar identidade; registrar um app não custa nada e não exige assinatura paga (não mude para "pagamento conforme o uso").

1. Crie a conta Azure gratuita em https://azure.microsoft.com/free entrando com a sua conta pessoal da Microsoft (a mesma do OneNote ou outra; o app só precisa morar em algum diretório).

2. Abra o Microsoft Entra em https://entra.microsoft.com → Aplicativos → Registros de aplicativo → Novo registro. (O menu do Entra muda de lugar de tempos em tempos, às vezes dentro de Identidade; se não achar, digite "Registros de aplicativo" na busca do topo do portal.)

   • Nome: onenote-mcp (ou outro).

   • Tipos de conta com suporte: Somente contas pessoais da Microsoft.

   • URI de redirecionamento: deixe em branco.

   • Clique em Registrar.

3. No app criado, menu Autenticação → Configurações avançadas → Permitir fluxos de cliente público = Sim → Salvar. Na tela nova de Autenticação, a mesma chave fica na aba Configurações. (Sem isso, o login por código dá erro.)

4. Menu Permissões de API → Adicionar uma permissão → Microsoft Graph → Permissões delegadas → marque Notes.ReadWrite → Adicionar permissões. Não precisa de mais nada: o offline_access (manter o login) vem sozinho.

5. Menu Visão geral: copie o ID do aplicativo (cliente) (um GUID como 00000000-0000-0000-0000-000000000000). Ele vai no client_id do passo 3.

Os nomes dos menus estão como aparecem no portal em português; em inglês são App registrations, New registration, Personal Microsoft accounts only, Authentication → Allow public client flows (aba Settings na tela nova), API permissions → Delegated permissions, Application (client) ID.

Passo 2: instalar

git clone https://github.com/dosxnjos/onenote-mcp.git
cd onenote-mcp

Com uv:

uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe -e .

(O --python 3.12 faz o uv usar o Python 3.12 da máquina, ou baixar um se não houver; sem ele, o uv pega o primeiro Python que achar, e um 3.11 daria erro de requires-python. Versão mais nova também serve: --python 3.13.)

Ou com pip:

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .

(No Windows, se o python do terminal for outra versão ou não existir, use o lançador: py -3.12 -m venv .venv.)

Instale com -e (modo editável): todos os comandos (login, eu, secoes, serve) procuram o config.toml na pasta do projeto. Se instalar de outro jeito, ou guardar o config.toml em outro lugar, aponte o arquivo pela variável de ambiente ONENOTE_MCP_CONFIG (caminho completo). Ela vale para todos os comandos: defina no terminal antes do login, eu e secoes (no PowerShell: $env:ONENOTE_MCP_CONFIG = "C:\caminho\config.toml"; no macOS/Linux: export ONENOTE_MCP_CONFIG=/caminho/config.toml) e no registro do servidor (passo 5). Sem ela, esses comandos dizem "falta o client_id" mesmo com o config preenchido.

Passo 3: configurar (config.toml)

copy config.exemplo.toml config.toml

(cp no macOS/Linux.) O config.toml fica fora do git. Chaves:

Como achar o caminho para permitidos: faça o login (passo 4) e rode .venv\Scripts\python.exe -m onenote_mcp eu: ele lista os nomes de todos os blocos da conta e marca os já liberados. Ponha o nome do bloco em permitidos (libera o bloco inteiro, menos as seções bloqueadas) e rode .venv\Scripts\python.exe -m onenote_mcp secoes: ele mostra o caminho completo de cada seção liberada. Para liberar só algumas, troque o nome do bloco pelos caminhos Bloco/Grupo/Seção que quiser. Maiúsculas e acentos não importam na comparação.

[lista]
permitidos = [
  "Meu Bloco/Trabalho/Reuniões",
  "Meu Bloco/Pessoal",
]

Bloco compartilhado por outra pessoa: abra o bloco no OneNote para a Web e copie o endereço do OneDrive que tem resid=.... Cole o link inteiro em blocos_extra: o servidor tira o id dele sozinho. (Se preferir montar o id à mão, é 0- + o valor do resid, trocando %21 por !: no link ele vem codificado.) Depois rode eu: o bloco aparece na lista com o nome a pôr em permitidos. Se o eu der erro 404, o id em blocos_extra está errado. O papel da sua conta (Reader ou Contributor) decide se dá para escrever: listar_blocos mostra.

[lista]
permitidos = ["Bloco da Equipe"]
blocos_extra = ["0-XXXXXXXXXXXXXXXX!sxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"]

Imagens e anexos: crie uma pasta só para isso e ponha em [arquivos].pastas. A home inteira, a raiz do disco e pastas que contêm o AppData ou o cache do servidor são recusadas. Tipos aceitos: imagens PNG, JPEG, GIF, BMP e TIFF (conferidas pelo conteúdo do arquivo, não só pela extensão) e anexos .pdf, .docx, .xlsx, .pptx, .zip, .txt e .csv. Outro tipo é recusado com erro.

[arquivos]
pastas = ["C:/Users/voce/OneNote-anexos"]

Instruções suas para o Claude: o servidor já diz ao Claude para ficar na lista permitida, ler a spec antes de escrever e escrever para o leitor da página. Para acrescentar regras suas (quem costuma ler, tom de voz):

[servidor]
instrucoes = """
Quem lê estas páginas: a equipe de vendas; explique toda sigla.
Tom: direto, frases curtas.
"""

O servidor relê o config.toml quando o arquivo muda (sem reiniciar); só as instrucoes pedem reiniciar o servidor, porque vão ao Claude na conexão.

Passo 4: login e conferência

.venv\Scripts\python.exe -m onenote_mcp login

Ele mostra um endereço da Microsoft e um código. Abra o endereço no navegador, cole o código e entre com a conta pessoal. A Microsoft pode pedir um código de verificação enviado por e-mail à conta antes de liberar: é normal. Em seguida vem a tela de consentimento: o app onenote-mcp (o seu, do passo 1, marcado como não verificado porque foi você que registrou) pede para ler e gravar suas anotações e manter o acesso. Aceite: é o escopo Notes.ReadWrite mais o offline_access do passo 1. No fim aparece conectado como <sua conta>. O login fica no cache cifrado e se renova sozinho.

Confira o que a lista libera:

.venv\Scripts\python.exe -m onenote_mcp eu        (conta logada e nomes de todos os blocos)
.venv\Scripts\python.exe -m onenote_mcp secoes    (seções liberadas, com o caminho; aceita um prefixo de bloco)

Para apagar o login: .venv\Scripts\python.exe -m onenote_mcp sair.

Passo 5: registrar no Claude

Claude Code (troque o caminho pela pasta onde você clonou):

claude mcp add -s user onenote -- C:\caminho\onenote-mcp\.venv\Scripts\python.exe -I -m onenote_mcp serve

O -I impede o Python de importar arquivos da pasta atual. Confira com claude mcp list ou /mcp dentro do Claude Code. Depois de atualizar o código ou as instrucoes, reinicie o Claude Code (ou /mcp → reconectar).

Claude Desktop: em Configurações → Desenvolvedor → Editar configuração (claude_desktop_config.json), acrescente:

{
  "mcpServers": {
    "onenote": {
      "command": "C:\\caminho\\onenote-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-I", "-m", "onenote_mcp", "serve"]
    }
  }
}

Se o config.toml estiver em outro lugar, acrescente "env": {"ONENOTE_MCP_CONFIG": "C:\\caminho\\config.toml"}. Outros clientes MCP: o comando é o mesmo, sempre com o Python do .venv (C:\caminho\onenote-mcp\.venv\Scripts\python.exe -I -m onenote_mcp serve, transporte stdio). O python do sistema não tem o pacote instalado e dá No module named onenote_mcp.

Como usar

Peça em linguagem natural; o Claude escolhe as tools. Exemplos:

• "Lista as seções que você enxerga no meu OneNote."

• "Lê a página mais recente da seção Reuniões e me resume as pendências."

• "Cria uma página 'Reunião 15/10' em Meu Bloco/Trabalho/Reuniões com pauta, tarefas e uma tabela de responsáveis."

• "Na página X, troca o prazo de 20/10 para 24/10 e marca a tarefa 'enviar orçamento' como feita."

• "Acrescenta esta foto no fim da página" (com a foto numa pasta de [arquivos].pastas).

Formato ONMD (resumo)

Markdown comum mais o que é do OneNote: títulos, cores (paleta de 9 nomes ou #hex), fundo, fonte, tamanho, alinhamento, realce, etiquetas oficiais, caixas de tarefa, listas (-, 1., a., i.), tabela simples e <tabela> rica (largura, fundo por célula), <destaque>, <colunas>, citação, bloco de código, divisória, <secao id> como alvo, links para página (pagina:<id>), imagens e anexos.

## Pendências {cor=azul}

- [ ] Fechar orçamento {tags=important}
- [x] Enviar fotos

<destaque cor=amarelo icone="💡">
**Prazo:** 03/11.
</destaque>

ONMD = OneNote + MD (markdown); arquivo nesse formato usa a extensão .onmd.

Spec completa (é o que o Claude lê pela tool ler_spec): onenote_mcp/formato/spec.md. Exemplo com toda a sintaxe: tests/vitrine.onmd, a "vitrine" do formato, usada no teste de ida e volta (ONMD → HTML do OneNote → ONMD tem que voltar igual). Provas contra o OneNote real: docs/provas-v2.md.

Por dentro: formato/escrita.py (ONMD → XHTML) e formato/leitura.py (HTML do OneNote → ONMD), com ida e volta testada; sanitizar.py é a 2ª barreira no HTML final; editar lê a página na hora, acha o bloco pelo trecho e regrava só ele (PATCH atômico), e recusa bloco com algo que o ONMD não mostra, para não apagar o que não aparece.

Segurança

• Nada se apaga: nenhuma tool apaga; o cliente HTTP não tem DELETE e o PATCH só aceita append, insert, prepend e replace com conteúdo visível (trocar por vazio ou por caractere invisível é recusado).

• A lista permitida limita a ferramenta, não a chave. O token vale para todos os blocos da conta, e qualquer programa rodando com o seu usuário consegue ler o cache cifrado. Senha não deveria morar no OneNote; bloco, grupo ou seção com "senha", "password" ou "credencia" em qualquer trecho do nome é bloqueado no código (o que também derruba nomes inocentes como "Resenhas": renomeie no OneNote se precisar). Para isolar de verdade, faça o login com uma conta separada que só recebe compartilhado o que o Claude pode ver.

• Token em cache cifrado em %LOCALAPPDATA%\onenote-mcp\token_cache.bin, nunca no repositório. python -m onenote_mcp sair apaga o login; para revogar o acesso do app, use account.microsoft.com → Privacidade → aplicativos com acesso.

• Escopo único Notes.ReadWrite; host fixo graph.microsoft.com, sem seguir redirecionamento; até 120 pedidos/min.

• Arquivo local só sai pelo parâmetro anexos e só de [arquivos].pastas; caminho escrito no texto da página nunca é lido.

• Texto lido de página é dado, não instrução (para o Claude e para o código).

Limites conhecidos

• Lista aninhada (sub-item) aparece com uma linha em branco antes de cada sub-nível: limite da Microsoft no Graph, sem contorno. A escrita avisa; prefira títulos ou lista de um nível.

• Parágrafo ou título logo antes de uma lista não se edita: o OneNote o moveria para depois da lista ao regravá-lo, e o que se insere "depois" dele também cai abaixo da lista; as tools recusam e explicam.

• Busca só pelo título das páginas: o Graph não oferece busca no texto.

• Imagem pequena ignora a largura pedida (fica no tamanho natural).

• Página nova leva até ~1 min para existir de fato: ler ou editar logo depois pode dar 404 ou 504. Às vezes a criação trava do lado da Microsoft (página sem título, 404 por minutos): crie de novo.

• Sem apagar página, seção ou bloco (de propósito); também não cria seção nem copia página.

• Numeração de lista sempre começa do 1; etiqueta em sub-item não é guardada; não há mesclar células.

Solução de problemas

Mais sintomas e causas: docs/ARMADILHAS.md.

Testes

Instale o pytest com o mesmo instalador do passo 2 e rode:

uv pip install --python .venv\Scripts\python.exe -e ".[teste]"     (com uv)
.venv\Scripts\python.exe -m pip install -e ".[teste]"             (com pip)
.venv\Scripts\python.exe -m pytest -q

Sem rede: um Graph falso e um simulador imitam o OneNote (341 testes; o de link simbólico é pulado no Windows sem permissão para criar link).

Licença

MIT.

Créditos

O mapa de endpoints e as pegadinhas de conta pessoal vieram do estudo do Softeria/ms-365-mcp-server (MIT). O desenho das tools de edição e da spec se inspirou nas instruções do MCP do Notion. Nenhum código copiado.