Servidor MCP de solo lectura de Notion

Este proyecto implementa un servidor MCP de solo lectura optimizado para la API de Notion, centrándose en el rendimiento y la eficiencia de los asistentes de IA para consultar y recuperar contenido de Notion.

Mejoras clave

Diseño de solo lectura : centrado exclusivamente en las operaciones de recuperación de datos, lo que garantiza un acceso seguro al contenido de Notion.
Conjunto de herramientas minimizado : se redujo la cantidad de herramientas API de Notion expuestas de más de 15 a solo 6 esenciales para el análisis de documentos.
Procesamiento paralelo : rendimiento mejorado al implementar solicitudes de API asincrónicas y paralelas para recuperar contenido de bloques, lo que reduce significativamente los tiempos de respuesta.
Acceso extendido a la base de datos : se agregó soporte para operaciones de recuperación de bases de datos, propiedades de página y comentarios.
Optimizado para asistentes de IA : la cantidad de herramientas significativamente reducida soluciona 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 de API estándar de Notion, lo que mejora el rendimiento y la compatibilidad con los asistentes de IA:

El conjunto de herramientas reducido ayuda a mantenerse dentro de los límites de herramientas recomendados para un rendimiento óptimo del asistente de IA y, al mismo tiempo, proporciona todas las funciones esenciales.

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 las API de Notion expuestas a operaciones de solo lectura, existe un riesgo considerable para los datos del espacio de trabajo al exponerlos a LLM. Los usuarios preocupados por la seguridad deberían configurar mejor las capacidades de la integración.

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

2. Agregar configuración MCP a su cliente:

Usando npm:

Agregue 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:

Agregue 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 olvides reemplazar ntn_**** con tu secreto de integración. Puedes encontrarlo en la pestaña de configuración de la integración.

3. Conectar el contenido con la integración:

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

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

Herramientas disponibles

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

API-retrieve-a-page : Obtener información de la página
API-get-block-children : Obtener bloques de contenido de 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 específica de la propiedad de una página
API-get-one-pager : ¡NUEVO! Recupera 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 las más de 15 de la implementación estándar), garantizamos:

Mejor rendimiento en asistentes de IA como Cursor y Claude que tienen limitaciones en el número de herramientas
Reducción de la carga cognitiva para los modelos de IA al elegir las herramientas adecuadas
Tiempos de respuesta más rápidos con menos opciones de API a considerar
Seguridad mejorada mediante una superficie API minimizada

Exploración automática de contenido

La nueva herramienta API-get-one-pager proporciona una forma poderosa de explorar páginas de Notion sin necesidad de múltiples llamadas API:

Recuperación recursiva : recorre automáticamente toda la estructura de la página, incluidos los bloques anidados.
Procesamiento paralelo : obtiene varios bloques y sus elementos secundarios simultáneamente para obtener el máximo rendimiento
Almacenamiento en caché inteligente : almacena los datos recuperados para minimizar las llamadas API redundantes
Contenido completo : incluye páginas, bloques, bases de datos, comentarios e información detallada de la propiedad.
Profundidad personalizable : controle el nivel de recursión para equilibrar entre detalle y rendimiento.

{
  "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 los asistentes de IA que necesitan comprender todo el contenido de una página de Notion sin realizar docenas de llamadas API independientes, lo que da como resultado respuestas mucho más rápidas y eficientes.

Procesamiento asincrónico

El servidor implementa técnicas avanzadas de procesamiento paralelo para manejar documentos Notion de gran tamaño:

Se agrupan y procesan varias solicitudes simultáneamente
La paginación se gestiona automáticamente para los elementos secundarios del bloque.
Los resultados se agregan de manera eficiente antes de ser devueltos.
El registro de la consola proporciona visibilidad del proceso sin afectar el formato de respuesta.

Ejemplos

Utilizando la siguiente instrucción:

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

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

Usando la información de la base de datos:

Get the structure of database 8a6b35e6e67f802fa7e1d27686f017f2

Desarrollo

Construir:

pnpm build

Ejecutar:

pnpm dev

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Beneficios del rendimiento del Asistente 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, conservando al mismo tiempo toda la funcionalidad esencial. El resultado es:

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

Notion ReadOnly MCP Server

Integrations