OneNote

Acesse toda a sua base de conhecimento do OneNote através de IA usando a API do Microsoft Graph.

GitHub
49
Experimente este MCPPatrocinado

Documentação

Servidor MCP do OneNote

Um servidor completo e robusto do Model Context Protocol (MCP) para integração com o Microsoft OneNote no Claude Desktop. Acesse toda a sua base de conhecimento do OneNote por meio de consultas em linguagem natural.

🎯 O Que Isso Faz

Transforme seus blocos de anotações do OneNote em uma base de conhecimento acessível por IA:

  • Liste todos os seus blocos de anotações, seções e páginas
  • Leia o conteúdo das páginas para análise e pesquisa
  • Consultas em linguagem natural como "Mostre minhas anotações de DevOps" ou "Encontre páginas sobre planejamento de projetos"
  • Autenticação OAuth segura com a API do Microsoft Graph
  • Tratamento de erros à prova de falhas com depuração detalhada

✨ Por Que Esta Implementação

Diferente de outros servidores MCP do OneNote, este:

  • ✅ Realmente funciona - testado extensivamente com dados reais do OneNote
  • ✅ Funcionalidade completa - todas as operações principais do OneNote implementadas
  • ✅ Autenticação robusta - fluxo de dispositivo em duas etapas que lida com casos extremos
  • ✅ Pronto para produção - tratamento de erros e registro adequados
  • ✅ Configuração fácil - instruções detalhadas para usuários não técnicos

🚀 Início Rápido

Pré-requisitos

1. Instalar o uv (se você não tiver)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# or with Homebrew
brew install uv

2. Clonar e Configurar

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

# Create virtual environment and install dependencies
uv sync

3. Registro do Aplicativo no Azure

Você precisa criar um aplicativo no Azure para acessar o OneNote. Não se preocupe, é gratuito e leva 5 minutos:

  1. Acesse o Portal do Azure (entre com sua conta Microsoft)
  2. Navegue até Azure Active Directory → Registros de aplicativos → Novo registro
  3. Preencha o formulário:
    • Nome: "Servidor MCP do OneNote" (ou o que você preferir)
    • Tipos de conta compatíveis: "Contas em qualquer diretório organizacional e contas pessoais da Microsoft"
    • URI de redirecionamento: Selecione "Cliente público/nativo" e insira: https://login.microsoftonline.com/common/oauth2/nativeclient
  4. Clique em Registrar
  5. Copie o ID do aplicativo (cliente) - você vai precisar dele!

4. Adicionar Permissões

Ainda no seu aplicativo do Azure:

  1. Acesse Permissões de API → Adicionar uma permissão
  2. Selecione Microsoft Graph → Permissões delegadas
  3. Adicione estas permissões:
    • Notes.Read - Ler blocos de anotações do OneNote
    • Notes.ReadWrite - Criar/modificar conteúdo do OneNote (opcional, mas recomendado)
    • User.Read - Ler perfil do usuário
  4. Clique em Conceder consentimento do administrador (o botão no topo)

5. Configurar o Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Adicione esta configuração (substitua /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather pelo seu caminho real):

Configuração básica:

{
  "mcpServers": {
    "onenote": {
      "command": "uv",
      "args": [
        "--directory", "/FULL/PATH/TO/onenote-mcp-server",
        "run", "python", "onenote_mcp_server.py"
      ],
      "env": {
        "AZURE_CLIENT_ID": "your-azure-client-id-here"
      }
    }
  }
}

Com controle explícito de cache de token:

{
  "mcpServers": {
    "onenote": {
      "command": "uv",
      "args": [
        "--directory", "/FULL/PATH/TO/onenote-mcp-server",
        "run", "python", "onenote_mcp_server.py"
      ],
      "env": {
        "AZURE_CLIENT_ID": "your-azure-client-id-here",
        "ONENOTE_CACHE_TOKENS": "true"
      }
    }
  }
}

Substitua /FULL/PATH/TO/onenote-mcp-server pelo caminho real deste projeto.

6. Reiniciar o Claude Desktop

Saia completamente e reinicie o Claude Desktop. Você deve ver as ferramentas do OneNote no menu 🔨.

🔐 Primeira Autenticação

  1. No Claude Desktop, diga: "Iniciar autenticação do OneNote"
  2. O Claude fornecerá uma URL e um código
  3. Visite a URL no seu navegador, insira o código e faça login
  4. Compatibilidade com navegadores:
    • ✅ Firefox (testado com 139.0.4) - funciona perfeitamente
    • ❌ Safari - pode ter problemas com o redirecionamento OAuth da Microsoft
    • ✅ Chrome/Edge - deve funcionar (navegadores da Microsoft)
  5. Volte ao Claude e diga: "Concluir autenticação do OneNote"
  6. Você está pronto para começar!

Persistência de Token

Por padrão, os tokens de autenticação são armazenados em cache com segurança na sua máquina local, para que você só precise autenticar uma vez a cada poucas semanas/meses.

Para desativar o cache de token (para ambientes sensíveis à segurança):

{
  "mcpServers": {
    "onenote": {
      "command": "uv",
      "args": [
        "--directory", "/FULL/PATH/TO/onenote-mcp-server",
        "run", "python", "onenote_mcp_server.py"
      ],
      "env": {
        "AZURE_CLIENT_ID": "YOUR_CLIENT_ID_HERE",
        "ONENOTE_CACHE_TOKENS": "false"
      }
    }
  }
}

Opções de cache de token:

  • ONENOTE_CACHE_TOKENS=true (padrão) - Os tokens persistem entre sessões
  • ONENOTE_CACHE_TOKENS=false - Autenticar a cada sessão (mais seguro)

📖 Exemplos de Uso

Após a autenticação, experimente estes comandos no Claude Desktop:

List my OneNote notebooks
Show me sections in my Work notebook  
What pages are in my Ideas section?
Read the content of my "Project Plan" page

🛠 Solução de Problemas

"Nenhuma ferramenta disponível" no Claude Desktop

  • Certifique-se de ter reiniciado o Claude Desktop após as alterações de configuração
  • Verifique se o caminho na sua configuração está correto (use o caminho absoluto completo)
  • Verifique se o uv está instalado: uv --version

Problemas de autenticação

  • Problemas de OAuth no Safari: O Safari pode não lidar corretamente com o redirecionamento OAuth da Microsoft - use Firefox ou Chrome
  • Solicitações "nativeclient": Comportamento normal do OAuth da Microsoft, mas se bloquear a autenticação, tente um navegador diferente
  • Autenticação expirada: Use "Verificar status de autenticação do OneNote" para ver a expiração do token
  • Limpar tokens em cache: Use "Limpar cache de token do OneNote" se precisar redefinir a autenticação
  • Navegadores recomendados: Firefox (funcionamento confirmado), Chrome ou Edge para melhor compatibilidade

Erros de "Comando não encontrado"

  • Certifique-se de que o uv está no seu PATH
  • Alternativa: substitua "uv" por "python" na configuração e use o caminho completo para o seu interpretador Python

Erros de permissão negada

  • Verifique as permissões de arquivo no diretório do seu projeto
  • Certifique-se de que o Claude Desktop pode ler os arquivos

🏗 Desenvolvimento

Estrutura do Projeto

onenote-mcp-server/
├── onenote_mcp_server.py      # Main server implementation
├── pyproject.toml             # Dependencies and metadata  
├── README.md                  # This file
├── LICENSE                    # MIT License
└── .gitignore                 # Git ignore rules

Principais Recursos

  • Autenticação em duas etapas: Lida corretamente com o fluxo de código do dispositivo
  • Integração completa com a API do Graph: Todas as operações do OneNote suportadas
  • Tratamento robusto de erros: Registro detalhado e falhas controladas
  • Framework FastMCP: Estrutura de código limpa e sustentável
  • Configuração por variáveis de ambiente: Tratamento seguro de credenciais

Adicionando Novos Recursos

O servidor é construído com FastMCP, facilitando a adição de novas ferramentas:

@mcp.tool()
async def your_new_tool(param: str) -> str:
    """Description of what your tool does."""
    # Your implementation here
    return result

🤝 Contribuições

Contribuições são bem-vindas! Por favor:

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Adicione testes para novas funcionalidades
  4. Envie um pull request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

  • Construído com o framework FastMCP
  • Usa a API do Microsoft Graph para acesso ao OneNote
  • Inspirado pelo incrível potencial da IA + bases de conhecimento pessoais

⚠️ Notas Importantes

  • Este servidor apenas lê/grava dados aos quais você já tem acesso
  • As credenciais do seu aplicativo Azure permanecem na sua máquina
  • Toda a autenticação acontece diretamente entre você e a Microsoft
  • Nenhum dado é enviado a terceiros

Feito com ❤️ para a comunidade Claude + OneNote

Transforme seu OneNote em uma base de conhecimento acessível por IA!