Notion ReadOnly MCP Server
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.
Related MCP server: notion-slim
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áginaAPI-get-block-children: Obtener bloques de contenido de página (con procesamiento paralelo)API-retrieve-a-block: obtener detalles sobre un bloque específicoAPI-retrieve-a-database: Obtener información de la base de datosAPI-retrieve-a-comment: Obtener comentarios en una página o bloqueAPI-retrieve-a-page-property: Obtener información específica de la propiedad de una páginaAPI-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.
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 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 1a6b35e6e67f802fa7e1d27686f017f2La 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 8a6b35e6e67f802fa7e1d27686f017f2Desarrollo
Construir:
pnpm buildEjecutar:
pnpm devLicencia
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
Available Tools
8 toolsAPI-get-background-resultC
Retrieve the result of a background processing request
Inputs: page_id (required).
API-get-block-childrenC
Retrieve block children
Inputs: block_id (required), start_cursor, page_size.
API-get-one-pagerB
Recursively retrieve a full Notion page with all its blocks, databases, and related content
Inputs: page_id (required), maxDepth, includeDatabases, includeComments, +5 more.
API-retrieve-a-blockC
Retrieve a block
Inputs: block_id (required).
API-retrieve-a-commentC
Retrieve comments
Inputs: block_id (required), start_cursor, page_size.
API-retrieve-a-databaseC
Retrieve a database
Inputs: database_id (required).
API-retrieve-a-pageC
Retrieve a page
Inputs: page_id (required), filter_properties.
API-retrieve-a-page-propertyC
Retrieve a page property item
Inputs: page_id (required), property_id (required), page_size, start_cursor.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have distinct purposes targeting specific Notion resources (blocks, pages, databases, comments, properties), but 'API-retrieve-a-block' and 'API-get-block-children' could cause confusion as both relate to blocks with overlapping retrieval functions. The descriptions help clarify, but the boundary isn't perfectly clear.
The naming follows a mostly consistent 'API-[verb]-a-[noun]' pattern for seven tools, but 'API-get-background-result' and 'API-get-one-pager' deviate with different verb structures ('get' vs 'retrieve') and compound nouns. This mixed convention reduces predictability, though the names remain readable.
With 8 tools, the count is well-scoped for a read-only Notion server, covering key retrieval operations without bloat. Each tool serves a clear purpose, making the set manageable and focused on the server's stated functionality.
For a read-only server, the tool set provides comprehensive coverage of Notion's core resources (pages, blocks, databases, comments, properties) and includes useful utilities like background result retrieval. A minor gap exists in lacking a tool for listing/searching across multiple resources, but agents can work around this with the available retrieval tools.
Maintenance
Related MCP Connectors
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted Airtable MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
The HubSpot MCP Server acts as a bridge that enables AI assistants and Large Language Models to securely interact with HubSpot CRM data through natural conversation, without requiring users to understand complex API structures. It provides read-only access to standard CRM objects (contacts, companies, deals, tickets, products, invoices, and more) and their associations, secured via OAuth 2.0, allowing AI agents to perform tasks like summarizing deals, fetching company updates, and looking up record changes.
Read-only Google Analytics 4 MCP server for AI assistants.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search, read, summarize, and analyze sentiment of Notion pages and databases, turning your Notion workspace into an intelligent, queryable knowledge system.MIT
- AlicenseNot gradedqualityDmaintenanceA token-optimized MCP server for Notion that reduces context window usage by 73% while preserving full functionality, enabling AI assistants to interact with Notion efficiently.20 npm2MIT
- AlicenseNot gradedqualityBmaintenanceA lightweight, read-only MCP server for Notion that enables searching, reading pages, and querying databases with token-efficient output and smart caching.32 npm5MIT
- AlicenseNot gradedqualityDmaintenanceFast, read-only MCP server for Notion that reads directly from local SQLite cache, enabling instant access to Notion pages, databases, and users without API calls or rate limits.2MIT