OneNote

Accede a toda tu base de conocimiento de OneNote a través de IA usando la API de Microsoft Graph.

GitHub
49
Prueba este MCPPatrocinado

Documentación

Servidor MCP de OneNote

Un servidor completo y robusto del Protocolo de Contexto de Modelo (MCP) para la integración de Microsoft OneNote con Claude Desktop. Accede a toda tu base de conocimientos de OneNote mediante consultas en lenguaje natural.

🎯 Qué Hace Esto

Transforma tus blocs de notas de OneNote en una base de conocimientos accesible por IA:

  • Lista todos tus blocs de notas, secciones y páginas
  • Lee el contenido de las páginas para análisis y búsqueda
  • Consultas en lenguaje natural como "Muéstrame mis notas de DevOps" o "Encuentra páginas sobre planificación de proyectos"
  • Autenticación OAuth segura con Microsoft Graph API
  • Manejo de errores a prueba de balas con depuración detallada

✨ Por Qué Esta Implementación

A diferencia de otros servidores MCP de OneNote, este:

  • ✅ Realmente funciona - probado exhaustivamente con datos reales de OneNote
  • ✅ Funcionalidad completa - todas las operaciones principales de OneNote implementadas
  • ✅ Autenticación robusta - flujo de dispositivo en dos pasos que maneja casos límite
  • ✅ Listo para producción - manejo de errores y registro adecuados
  • ✅ Configuración fácil - instrucciones detalladas para usuarios no técnicos

🚀 Inicio Rápido

Requisitos Previos

  • Python 3.10+
  • uv package manager (recomendado) o pip
  • Claude Desktop
  • Cuenta de Microsoft Azure (gratuita)

1. Instalar uv (si no lo tienes)

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

# or with Homebrew
brew install uv

2. Clonar y 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 de Aplicación en Azure

Necesitas crear una aplicación de Azure para acceder a OneNote. No te preocupes, es gratis y toma 5 minutos:

  1. Ve al Azure Portal (inicia sesión con tu cuenta de Microsoft)
  2. Navega a Azure Active Directory → App registrations → New registration
  3. Completa el formulario:
    • Name: "OneNote MCP Server" (o lo que prefieras)
    • Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
    • Redirect URI: Selecciona "Public client/native" e ingresa: https://login.microsoftonline.com/common/oauth2/nativeclient
  4. Haz clic en Register
  5. Copia el Application (client) ID - ¡lo necesitarás!

4. Agregar Permisos

Todavía en tu aplicación de Azure:

  1. Ve a API permissions → Add a permission
  2. Selecciona Microsoft Graph → Delegated permissions
  3. Agrega estos permisos:
    • Notes.Read - Leer blocs de notas de OneNote
    • Notes.ReadWrite - Crear/modificar contenido de OneNote (opcional pero recomendado)
    • User.Read - Leer perfil de usuario
  4. Haz clic en Grant admin consent (el botón en la parte superior)

5. Configurar Claude Desktop

Edita tu archivo de configuración de Claude Desktop:

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

Agrega esta configuración (reemplaza /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather con tu ruta real):

Configuración 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"
      }
    }
  }
}

Con control explícito de caché de tokens:

{
  "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"
      }
    }
  }
}

Reemplaza /FULL/PATH/TO/onenote-mcp-server con la ruta real de este proyecto.

6. Reiniciar Claude Desktop

Cierra y reinicia completamente Claude Desktop. Deberías ver las herramientas de OneNote en el menú 🔨.

🔐 Autenticación por Primera Vez

  1. En Claude Desktop, di: "Start OneNote authentication"
  2. Claude te dará una URL y un código
  3. Visita la URL en tu navegador, ingresa el código e inicia sesión
  4. Compatibilidad del navegador:
    • ✅ Firefox (probado con 139.0.4) - funciona perfectamente
    • ❌ Safari - puede tener problemas con la redirección OAuth de Microsoft
    • ✅ Chrome/Edge - debería funcionar (navegadores de Microsoft)
  5. Vuelve a Claude y di: "Complete OneNote authentication"
  6. ¡Estás listo para empezar!

Persistencia de Tokens

Por defecto, los tokens de autenticación se almacenan en caché de forma segura en tu máquina local, por lo que solo necesitas autenticarte una vez cada pocas semanas/meses.

Para deshabilitar el caché de tokens (para entornos sensibles a la seguridad):

{
  "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"
      }
    }
  }
}

Opciones de caché de tokens:

  • ONENOTE_CACHE_TOKENS=true (predeterminado) - Los tokens persisten entre sesiones
  • ONENOTE_CACHE_TOKENS=false - Autenticar en cada sesión (más seguro)

📖 Ejemplos de Uso

Una vez autenticado, prueba estos comandos en 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

🛠 Solución de Problemas

"No tools available" en Claude Desktop

  • Asegúrate de haber reiniciado Claude Desktop después de los cambios de configuración
  • Verifica que la ruta en tu configuración sea correcta (usa la ruta absoluta completa)
  • Verifica que uv esté instalado: uv --version

Problemas de autenticación

  • Problemas de OAuth en Safari: Safari puede no manejar correctamente la redirección OAuth de Microsoft - usa Firefox o Chrome en su lugar
  • Avisos de "nativeclient": Comportamiento normal de OAuth de Microsoft, pero si bloquea la autenticación, prueba con otro navegador
  • Autenticación expirada: Usa "Check OneNote authentication status" para ver la expiración del token
  • Limpiar tokens en caché: Usa "Clear OneNote token cache" si necesitas restablecer la autenticación
  • Navegadores recomendados: Firefox (confirmado que funciona), Chrome o Edge para la mejor compatibilidad

Errores de "Command not found"

  • Asegúrate de que uv esté en tu PATH
  • Alternativa: reemplaza "uv" con "python" en la configuración y usa la ruta completa a tu intérprete de Python

Errores de permiso denegado

  • Verifica los permisos de archivo en tu directorio de proyecto
  • Asegúrate de que Claude Desktop pueda leer los archivos

🏗 Desarrollo

Estructura del Proyecto

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

Características Clave

  • Autenticación en dos pasos: Maneja correctamente el flujo de código de dispositivo
  • Integración completa con Graph API: Todas las operaciones de OneNote compatibles
  • Manejo robusto de errores: Registro detallado y fallos controlados
  • Framework FastMCP: Estructura de código limpia y mantenible
  • Configuración mediante variables de entorno: Manejo seguro de credenciales

Agregar Nuevas Funcionalidades

El servidor está construido con FastMCP, lo que facilita agregar nuevas herramientas:

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

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

  1. Haz un fork del repositorio
  2. Crea una rama de funcionalidad
  3. Agrega pruebas para la nueva funcionalidad
  4. Envía un pull request

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

  • Construido con el framework FastMCP
  • Usa Microsoft Graph API para el acceso a OneNote
  • Inspirado por el increíble potencial de la IA + las bases de conocimiento personales

⚠️ Notas Importantes

  • Este servidor solo lee/escribe datos a los que ya tienes acceso
  • Tus credenciales de la aplicación de Azure permanecen en tu máquina
  • Toda la autenticación ocurre directamente entre tú y Microsoft
  • No se envían datos a terceros

Construido con ❤️ para la comunidad de Claude + OneNote

¡Convierte tu OneNote en una base de conocimientos accesible por IA!