Notion ReadOnly MCP Server

Notion ReadOnly MCP Server

Este proyecto implementa un servidor MCP de solo lectura optimizado para la API de Notion, centrado en el rendimiento y la eficiencia para que los asistentes de IA consulten y recuperen contenido de Notion.

Mejoras Clave

• Diseño de Solo Lectura: Centrado exclusivamente en operaciones de recuperación de datos, garantizando un acceso seguro al contenido de Notion.
• Conjunto de Herramientas Minimizado: Redujo el número de herramientas expuestas de la API de Notion de más de 15 a solo 6 esenciales para el análisis de documentos.
• Procesamiento Paralelo: Rendimiento mejorado mediante la implementación de solicitudes API asíncronas y paralelas para recuperar contenido de bloques, reduciendo significativamente los tiempos de respuesta.
• Acceso Extendido a Bases de Datos: Se añadió soporte para operaciones de recuperación de bases de datos, propiedades de páginas y comentarios.
• Optimizado para Asistentes de IA: La reducción significativa del número de herramientas aborda el problema de "Demasiadas herramientas pueden degradar el rendimiento" en asistentes de IA como Cursor, que limita los modelos a aproximadamente 40 herramientas.

Comparación de Herramientas

Esta implementación de solo lectura expone muchas menos herramientas en comparación con la integración estándar de la API de Notion, mejorando el rendimiento y la compatibilidad con asistentes de IA:

El conjunto reducido de herramientas ayuda a mantenerse dentro de los límites recomendados para un rendimiento óptimo del asistente de IA, al tiempo que proporciona toda la funcionalidad esencial.

Instalación

1. Configuración de la Integración en Notion:

Vaya a https://www.notion.so/profile/integrations y cree una nueva integración interna o seleccione una existente.

Si bien limitamos el alcance de la API de Notion expuesta a operaciones de solo lectura, existe un riesgo no nulo para los datos del espacio de trabajo al exponerlos a los LLM. Los usuarios preocupados por la seguridad pueden querer configurar aún más las Capacidades de la Integración.

Por ejemplo, puede crear un token de integración de solo lectura otorgando únicamente acceso de "Lectura de contenido" desde la pestaña "Configuración":

2. Añadir la configuración de MCP a su cliente:

Usando npm:

Añada lo siguiente a su .cursor/mcp.json o claude_desktop_config.json (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "notion-readonly-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2022-06-28\" }"
      }
    }
  }
}

Usando Docker:

Añada lo siguiente a su .cursor/mcp.json o claude_desktop_config.json:

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "taewoong1378/notion-readonly-mcp-server"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

No olvide reemplazar ntn_**** con su secreto de integración. Puede encontrarlo en la pestaña de configuración de su integración.

3. Conexión de contenido a la integración:

Asegúrese de que las páginas y bases de datos relevantes estén conectadas a su integración.

Para hacerlo, visite la página, haga clic en los 3 puntos y seleccione "Conectar a la integración".

Herramientas Disponibles

Este servidor optimizado expone solo las herramientas esenciales de solo lectura de la API de Notion:

• API-retrieve-a-page: Obtener información de la página
• API-get-block-children: Obtener bloques de contenido de la página (con procesamiento paralelo)
• API-retrieve-a-block: Obtener detalles sobre un bloque específico
• API-retrieve-a-database: Obtener información de la base de datos
• API-retrieve-a-comment: Obtener comentarios en una página o bloque
• API-retrieve-a-page-property: Obtener información de propiedad específica de una página
• API-get-one-pager: ¡NUEVO! Recuperar recursivamente una página completa de Notion con todos sus bloques, bases de datos y contenido relacionado en una sola llamada

Al limitarnos a estas 7 herramientas esenciales (en comparación con más de 15 en la implementación estándar), garantizamos:

1. Mejor rendimiento en asistentes de IA como Cursor y Claude que tienen limitaciones en el número de herramientas
2. Carga cognitiva reducida para los modelos de IA al elegir herramientas apropiadas
3. Tiempos de respuesta más rápidos con menos opciones de API a considerar
4. Seguridad mejorada mediante una superficie de API minimizada

Exploración Automática de Contenido

La nueva herramienta API-get-one-pager proporciona una forma potente de explorar páginas de Notion sin requerir múltiples llamadas a la API:

• Recuperación recursiva: Recorre automáticamente toda la estructura de la página, incluidos los bloques anidados
• Procesamiento paralelo: Obtiene múltiples bloques y sus hijos simultáneamente para un rendimiento máximo
• Caché inteligente: Almacena los datos recuperados para minimizar llamadas API redundantes
• Contenido completo: Incluye páginas, bloques, bases de datos, comentarios e información detallada de propiedades
• Profundidad personalizable: Controle el nivel de recursión para equilibrar entre detalle y rendimiento

Uso de la Herramienta One Pager

{
  "page_id": "YOUR_PAGE_ID",
  "maxDepth": 5,               // Optional: Maximum recursion depth (default: 5)
  "includeDatabases": true,    // Optional: Include linked databases (default: true)
  "includeComments": true,     // Optional: Include comments (default: true)
  "includeProperties": true    // Optional: Include detailed page properties (default: true)
}

Esta capacidad de exploración automática es especialmente útil para asistentes de IA que necesitan comprender todo el contenido de una página de Notion sin realizar docenas de llamadas API separadas, lo que resulta en respuestas mucho más rápidas y eficientes.

Procesamiento Asíncrono

El servidor implementa técnicas avanzadas de procesamiento paralelo para manejar documentos grandes de Notion:

• Múltiples solicitudes se agrupan y procesan de forma concurrente
• La paginación se maneja automáticamente para los bloques hijos
• Los resultados se agregan de manera eficiente antes de devolverse
• El registro en consola proporciona visibilidad del proceso sin afectar el formato de respuesta

Ejemplos

1. Usando la siguiente instrucción:

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

La IA recuperará los detalles de la página de manera eficiente con procesamiento paralelo del contenido de los bloques.

2. Usando información de la base de datos:

Get the structure of database 8a6b35e6e67f802fa7e1d27686f017f2

Desarrollo

Compilar:

pnpm build

Ejecutar:

pnpm dev

Licencia

MIT

Beneficios de Rendimiento para Asistentes de IA

Los asistentes de IA modernos como Cursor y Claude tienen limitaciones en la cantidad de herramientas que pueden manejar de manera efectiva:

• La mayoría de los modelos pueden no respetar más de 40 herramientas en total
• Demasiadas herramientas pueden degradar el rendimiento general y las capacidades de razonamiento
• Los conjuntos de herramientas complejos aumentan la latencia de respuesta y la dificultad de toma de decisiones

Esta implementación de solo lectura reduce deliberadamente la superficie de la API de Notion para abordar estas limitaciones mientras preserva toda la funcionalidad esencial. El resultado es:

• Respuestas más rápidas y confiables de los asistentes de IA
• Precisión mejorada al interactuar con contenido de Notion
• Mejor rendimiento general mediante un diseño de API enfocado