Skip to main content
Glama

Easy Notion MCP

Servidor MCP centrado en Markdown que conecta agentes de IA a Notion. Los agentes escriben markdown — easy-notion-mcp lo convierte a la API de bloques de Notion y viceversa.

43 herramientas · 24 tipos de bloque · ~6–7× menos tokens de respuesta que el MCP oficial de Notion · Compatibilidad de ida y vuelta documentada

npm license node Discord Glama

npx easy-notion-mcp

Verlo en acción → Página de Notion en vivo creada y gestionada íntegramente mediante easy-notion-mcp.

Raw JSON chaos vs clean markdown


Contenido: Comparación · Configuración inicial · Perfiles de CLI · Configuración · Por qué Markdown · Cómo funciona · Herramientas · Recursos de MCP · Tipos de bloque · Ida y vuelta · Bases de datos · Recetario · Seguridad · Estabilidad · Preguntas frecuentes · Comunidad

¿Cómo se compara easy-notion-mcp con otros servidores MCP de Notion?

Feature

easy-notion-mcp

Official Notion MCP (npm)

better-notion-mcp

Formato de contenido

✅ Markdown GFM estándar

❌ JSON sin procesar de la API de Notion

⚠️ Markdown (tipos de bloque limitados)

Tipos de bloque

✅ 24 (desplegables, columnas, destacados, ecuaciones, incrustaciones, tablas, subidas de archivos, listas de tareas)

⚠️ Todos (como JSON sin procesar)

⚠️ ~7 (encabezados, párrafos, listas, código, citas, divisores)

Compatibilidad de ida y vuelta

✅ 24 tipos de bloque, salvedades documentadas

❌ El JSON sin procesar requiere reconstrucción de bloques

⚠️ Los bloques no compatibles se descartan silenciosamente

Herramientas

43 herramientas con nombre individual

18 autogeneradas a partir de OpenAPI

9 herramientas compuestas (39 acciones)

Subida de archivos

✅ file:///path en markdown

❌ Solicitud de función abierta

✅ Ciclo de vida de 5 pasos

Defensa contra inyección de prompts

✅ Prefijo de aviso de contenido + saneamiento de URL

❌

❌

Formato de entrada de base de datos

Pares clave-valor simples {"Status": "Done"}

Pares clave-valor simplificados

Pares clave-valor simplificados

Opciones de autenticación

Token de API u OAuth

Token de API u OAuth

Token de API u OAuth

¿Cuántos tokens ahorra easy-notion-mcp?

Leer el contenido de una página cuesta aproximadamente 6–7× menos tokens de respuesta que el servidor MCP oficial de Notion, porque el JSON sin procesar de bloques de Notion incluye metadatos por bloque (IDs de bloque, marcas de tiempo, objetos de autor) que un agente que lee para obtener contenido nunca necesita. Normalmente ~5–7×, desde ~3× en páginas con mucho código hasta ~15× en páginas ricas, con ≥94% del contenido de la página conservado. Medido frente al servidor oficial de JSON sin procesar; aproximadamente a la par con otros servidores basados en Markdown.

La ventaja es la omisión de metadatos, no la eficiencia de codificación. Con la misma información, los dos formatos cuestan aproximadamente lo mismo (la proporción común de representación intermedia es de ~1.0–1.06× en formas de página totalmente representadas, y 1.32× en prosa típica), por lo que el ahorro son los metadatos por bloque (UUIDs de bloque, marcas de tiempo, objetos de autor, envoltorios de anotaciones) que el JSON sin procesar incluye y una lectura de contenido nunca utiliza. Las consultas a bases de datos muestran una ventaja similar de ~7× con completitud total del contenido.

Metodología, resultados por clase y todas las salvedades: .meta/research/token-bench-results-2026-06-13.md (re-ejecutado mediante scripts/bench/lib/recompute-tiers.ts).

Related MCP server: MCP Notion Server (@suncreation)

¿Cómo configuro easy-notion-mcp?

Con token de API

Crea una integración de Notion, copia el token y comparte tus páginas con ella.

Claude Code:

claude mcp add notion -s user \
  -e NOTION_TOKEN=ntn_your_integration_token \
  -- npx -y easy-notion-mcp

Esto registra el servidor en la configuración a nivel de usuario de tu Claude Code (-s user) y pasa NOTION_TOKEN directamente al proceso hijo de MCP mediante -e. Tu entorno de shell y tus rcfiles no se modifican: el token vive en el archivo de configuración de Claude Code, limitado a este servidor, y no es visible para otros procesos. Para establecer una página principal predeterminada para create_page, añade -e NOTION_ROOT_PAGE_ID=<page-id> al mismo comando.

OpenClaw:

openclaw config set mcpServers.notion.command "npx"
openclaw config set mcpServers.notion.args '["-y","easy-notion-mcp"]'

Luego proporciona el token a través del entorno de shell padre antes de iniciar OpenClaw:

export NOTION_TOKEN=ntn_your_integration_token

Esta forma de export es el recurso genérico para cualquier cliente MCP que herede el entorno de shell padre. Advertencia: solo persiste durante la sesión de shell actual, a menos que lo añadas a tu rcfile de shell, lo cual tiene sus propias implicaciones de seguridad: prefiere la forma -e anterior cuando uses Claude Code específicamente.

Claude Desktop / Cursor / Windsurf — añádelo a tu archivo de configuración de MCP:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token"
      }
    }
  }
}

Ubicaciones de los archivos de configuración: Claude Desktop → claude_desktop_config.json · Cursor → .cursor/mcp.json · Windsurf → ~/.windsurf/mcp.json

{
  "servers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token"
      }
    }
  }
}

Perfiles de CLI para acceso a Notion de bajo contexto

Usa la CLI easy-notion cuando un agente necesite acceso a Notion sin cargar toda la superficie de herramientas de MCP, o cuando quieras integraciones de Notion separadas para distintos modos de permiso. Los perfiles viven en ~/.config/easy-notion-mcp/profiles.json de forma predeterminada y hacen referencia a nombres de variables de entorno, no a tokens sin procesar.

export NOTION_WORK_READONLY=ntn_readonly_token
export NOTION_WORK_WRITE=ntn_readwrite_token

npx -y --package easy-notion-mcp easy-notion profile add work-ro \
  --token-env NOTION_WORK_READONLY \
  --mode readonly \
  --default

npx -y --package easy-notion-mcp easy-notion profile add work-rw \
  --token-env NOTION_WORK_WRITE \
  --mode readwrite \
  --root-page-id your_root_page_id

Los comandos de lectura funcionan con perfiles de solo lectura:

npx -y --package easy-notion-mcp easy-notion --profile work-ro search "roadmap" --filter pages
npx -y --package easy-notion-mcp easy-notion --profile work-ro page read PAGE_ID --include-metadata
npx -y --package easy-notion-mcp easy-notion --profile work-ro content search-in-page PAGE_ID --query "launch" --within-toggle "Script"

Los comandos de mutación requieren un perfil de lectura/escritura:

npx -y --package easy-notion-mcp easy-notion --profile work-rw content append PAGE_ID --markdown "## Update"
npx -y --package easy-notion-mcp easy-notion --profile work-rw content update-toggle PAGE_ID --title "Script" --markdown-file ./script.md
npx -y --package easy-notion-mcp easy-notion --profile work-rw content archive-toggle PAGE_ID --title "Done"
npx -y --package easy-notion-mcp easy-notion --profile work-rw content restore-toggle ARCHIVED_BLOCK_ID

Los comandos destructivos de la CLI admiten --dry-run como una verificación previa de solo lectura. Ejecuta la misma búsqueda y validación de markdown cuando es posible, devuelve los campos planificados como would_delete_block_ids, would_update, would_archive o would_restore, y no muta Notion.

La skill ligera para el enrutamiento de agentes se publica en este repositorio en skills/easy-notion-cli/. Enseña a los agentes a preferir la CLI para el acceso a Notion basado en perfiles en lugar de registrar múltiples servidores MCP.

Con OAuth

Token de API + stdio es la opción predeterminada de menor fricción. Si estás ejecutando un despliegue compartido o quieres acceso por usuario, OAuth gestiona la autenticación sin necesidad de copiar y pegar ningún token.

Inicia el servidor:

npx -p easy-notion-mcp easy-notion-mcp-http

Requiere las variables de entorno NOTION_OAUTH_CLIENT_ID y NOTION_OAUTH_CLIENT_SECRET. Consulta Configuración de OAuth a continuación.

Claude Code:

claude mcp add notion --transport http http://localhost:3333/mcp

OpenClaw:

openclaw config set mcpServers.notion.transport "http"
openclaw config set mcpServers.notion.url "http://localhost:3333/mcp"

Claude Desktop:

Ve a Configuración → Conectores → Añadir conector personalizado e introduce http://localhost:3333/mcp.

Tu navegador se abrirá en la página de autorización de Notion. Elige las páginas que quieras compartir, haz clic en Permitir y listo.

Si quieres registrar easy-notion-mcp por proyecto en lugar de para todo el usuario, pega lo siguiente en un archivo .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "easy-notion-mcp": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token",
        "NOTION_ROOT_PAGE_ID": "your_root_page_id"
      }
    }
  }
}

Sustituye los valores de marcador de posición por tu token real de integración de Notion y el ID de página raíz (opcional). Ten en cuenta que este archivo debe vivir en tu proyecto, no en este repositorio: Claude Code registrará automáticamente cualquier servidor que encuentre en un .mcp.json de ámbito de proyecto e intentará iniciarlo, por lo que hacer commit de uno con credenciales de marcador de posición provocará "Failed to connect" al abrir el repositorio.

Dify / n8n / FlowiseAI (plataformas basadas en Docker):

Ejecuta el servidor HTTP en tu máquina anfitriona:

export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token \
  NOTION_MCP_BIND_HOST=0.0.0.0 \
  NOTION_MCP_BEARER=$NOTION_MCP_BEARER \
  npx -p easy-notion-mcp easy-notion-mcp-http

En la configuración del servidor MCP de tu plataforma, usa host.docker.internal en lugar de localhost, y añade el bearer a las cabeceras de las solicitudes:

http://host.docker.internal:3333/mcp
Authorization: Bearer <your NOTION_MCP_BEARER value>

¿Por qué no localhost? Estas plataformas normalmente se ejecutan en Docker. localhost dentro de un contenedor se refiere al propio contenedor, no a tu máquina anfitriona. host.docker.internal salva esa distancia.

Host HTTP y bearer: El servidor HTTP se vincula a 127.0.0.1 de forma predeterminada y el modo de token estático requiere NOTION_MCP_BEARER. host.docker.internal alcanza la IP de puente del host, así que establece NOTION_MCP_BIND_HOST=0.0.0.0 en el host y envía la cabecera bearer en cada solicitud del cliente. El modo OAuth, que emite bearers por usuario, es la alternativa para despliegues Docker compartidos.

easy-notion-mcp funciona con cualquier cliente compatible con MCP. El servidor se ejecuta mediante stdio (modo token de API) o HTTP (modo OAuth o token de API).

Si tienes preguntas durante la configuración, la comunidad de Discord es un buen lugar para preguntar. El canal #easy-notion-mcp cubre la configuración y el debate de diseño. Los errores van a GitHub issues.

Configuración

Modo stdio (token de API)

Variable

Required

Default

Description

NOTION_TOKEN

Sí

—

Token de integración de la API de Notion

NOTION_ROOT_PAGE_ID

No

—

ID de página principal predeterminado

NOTION_TRUST_CONTENT

No

false

Omitir el aviso de contenido en las respuestas de lectura de markdown (read_page, read_section, read_block, read_toggle)

Acerca de los archivos .env (solo para colaboradores): easy-notion-mcp carga un archivo .env desde el directorio de trabajo actual mediante dotenv. En la práctica, esto significa que .env solo "funciona" cuando ejecutas el servidor desde un clon del repositorio (node dist/index.js después de npm install && npm run build), porque la raíz del repositorio es tu directorio de trabajo. No se carga cuando el paquete se invoca mediante npx easy-notion-mcp o una instalación global desde un directorio arbitrario; ese es el comportamiento estándar de la CLI de npm. Para la ruta de npx, pasa NOTION_TOKEN mediante la bandera -e en la configuración de Claude Code anterior, o mediante el bloque env de la configuración de tu cliente MCP.

Transporte OAuth / HTTP

Ejecuta npx -p easy-notion-mcp easy-notion-mcp-http para iniciar el servidor HTTP con soporte OAuth.

Variable

Requerido

Predeterminado

Descripción

NOTION_OAUTH_CLIENT_ID

Sí (modo OAuth)

—

ID de cliente OAuth de la integración pública de Notion

NOTION_OAUTH_CLIENT_SECRET

Sí (modo OAuth)

—

Secreto de cliente OAuth de la integración pública de Notion

PORT

No

3333

Puerto del servidor HTTP

OAUTH_REDIRECT_URI

No

http://localhost:{PORT}/callback

URL de devolución de llamada OAuth

NOTION_MCP_BIND_HOST

No

127.0.0.1

Dirección de enlace. El valor predeterminado es loopback; establece 0.0.0.0 para que sea accesible desde la red, o una interfaz específica como 192.168.1.5.

NOTION_MCP_BEARER

Sí (modo de token estático)

—

Bearer de secreto compartido requerido por los clientes en el modo HTTP de token estático. El servidor se niega a iniciarse sin él. No es necesario en el modo OAuth.

Para obtener credenciales OAuth, crea una integración pública en notion.so/profile/integrations y configura http://localhost:3333/callback como URI de redirección.

En el modo OAuth, create_page funciona sin NOTION_ROOT_PAGE_ID — las páginas se crean en la sección privada del espacio de trabajo del usuario de forma predeterminada.

Postura de seguridad del modo HTTP

El transporte HTTP está diseñado para redes de confianza: autoalojamiento de un solo operador con un secreto bearer, u OAuth para implementaciones compartidas. No está endurecido para la exposición directa a Internet; coloca un proxy inverso con TLS delante si necesitas acceso remoto.

El modo de token estático requiere un bearer. Iniciar npx -p easy-notion-mcp easy-notion-mcp-http con solo NOTION_TOKEN configurado hará que se niegue a iniciarse. Establece un bearer de secreto compartido en el entorno del servidor y luego configura tu cliente MCP para que lo envíe como Authorization: Bearer <secret> en cada solicitud /mcp:

export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token npx -p easy-notion-mcp easy-notion-mcp-http

El bearer se compara con crypto.timingSafeEqual. Los bearers ausentes o incorrectos reciben 401 { "error": "invalid_token" }. Rota el secreto reiniciando el servidor con un valor nuevo.

El enlace predeterminado es loopback. El servidor se enlaza a 127.0.0.1 de forma predeterminada: solo procesos locales. Establece NOTION_MCP_BIND_HOST=0.0.0.0 para exponer todas las interfaces, o una IP específica como 192.168.1.5 para exponer una. El bearer es obligatorio independientemente del enlace.

Bearer-siempre es el límite de confianza. La protección contra el reenlace de DNS no está implementada en el endpoint /mcp, y el CORS en los endpoints de registro/token de OAuth (/register, /token, /revoke) es permisivo. Trata el bearer, o el bearer por usuario de OAuth, como lo único que se interpone entre la red y tu espacio de trabajo de Notion. Mantenlo configurado incluso para implementaciones solo de loopback. Si necesitas exponer este servidor más allá de una red de confianza, colócalo detrás de un proxy inverso que gestione TLS y las comprobaciones de origen.

Modo OAuth para multiusuario / remoto. OAuth tiene su propia aplicación del bearer por usuario; NOTION_MCP_BEARER no es necesario en el modo OAuth. Para implementaciones compartidas, el modelo de identidad por usuario de OAuth es la forma adecuada: token estático + bearer está pensado para el autoalojamiento de un solo operador.

Las subidas file:// son solo stdio. El markdown pasado a create_page, append_content, replace_content, update_section o update_page.cover con URLs file:// se rechaza a través de HTTP. Usa el modo stdio para flujos de trabajo con archivos locales (create_page_from_file también es solo stdio), o aloja el archivo en una URL HTTPS y usa esa URL en el markdown.

¿Por qué markdown primero?

El paquete npm oficial de Notion MCP devuelve JSON crudo de la API: objetos de bloque profundamente anidados con ~120 tokens de metadatos por bloque. Otros servidores convierten a markdown, pero solo admiten un puñado de tipos de bloque, descartando silenciosamente callouts, toggles, tablas, ecuaciones y más.

easy-notion-mcp utiliza markdown GFM estándar que los agentes ya conocen. No hay nada nuevo que aprender, ni sintaxis de etiquetas personalizadas, ni objetos de bloque que construir. El agente escribe markdown, easy-notion-mcp se encarga de la conversión a la API de bloques de Notion — y de vuelta, con 24 tipos de bloque preservados.

Esto significa que los agentes pueden editar contenido existente. Lee una página, obtén markdown de vuelta, modifica la cadena, escríbela de nuevo. El formato y la estructura admitidos se conservan para los tipos de bloque que este servidor representa, y las omisiones y degradaciones conocidas se documentan a continuación. Los agentes editan páginas de Notion de la misma manera que editan código, como texto.

¿Cómo funciona easy-notion-mcp?

Páginas — escribe y lee markdown:

create_page({
  title: "Sprint Review",
  markdown: "## Decisions\n\n- Ship v2 by Friday\n- [ ] Update deploy scripts\n\n> [!WARNING]\n> Deploy window is Saturday 2–4am only"
})

Léelo de vuelta — sale el mismo markdown:

read_page({ page_id: "..." })
{ "markdown": "## Decisions\n\n- Ship v2 by Friday\n- [ ] Update deploy scripts\n\n> [!WARNING]\n> Deploy window is Saturday 2–4am only" }

Modifica la cadena, llama a replace_content, listo. O apunta a una sola sección por nombre de encabezado con update_section. O haz un find_replace quirúrgico sin tocar el resto de la página. Las páginas también pueden tener iconos emoji e imágenes de portada configurados mediante create_page o update_page.

Bases de datos — escribe pares clave-valor simples:

add_database_entry({
  database_id: "...",
  properties: { "Status": "Done", "Priority": "High", "Due": "2026-05-15", "Tags": ["v2", "launch"] }
})

Sin objetos de tipo de propiedad, sin envoltorios anidados { select: { name: "Done" } }. easy-notion-mcp obtiene el esquema de la base de datos en tiempo de ejecución y convierte automáticamente. Los agentes pasan { "Status": "Done" }, easy-notion-mcp hace el resto.

Los errores te dicen cómo solucionarlos. Un nombre de encabezado incorrecto devuelve los encabezados disponibles. Una página faltante sugiere compartirla con la integración. Un filtro incorrecto te dice que llames a get_database primero. Los agentes pueden autocorregirse sin pedir ayuda al usuario.

El contenido complejo funciona. Los toggles anidados dentro de toggles, las columnas con tipos de contenido mixtos (listas + bloques de código + blockquotes), el anidamiento profundo de listas y el unicode completo (japonés, chino, árabe, emoji) están cubiertos por pruebas de ida y vuelta. La búsqueda de encabezados de update_section no distingue entre mayúsculas y minúsculas y devuelve los encabezados disponibles si no encuentra. add_database_entries maneja fallos parciales, y las entradas exitosas y fallidas se devuelven por separado para que los agentes puedan reintentar solo las fallidas.

¿Qué herramientas proporciona easy-notion-mcp?

easy-notion-mcp incluye 43 herramientas con nombre individual en 7 categorías (42 a través de HTTP, lo que excluye create_page_from_file, que es solo stdio). Las descripciones de las herramientas mantienen el comportamiento crítico para la seguridad en línea y apuntan a recursos MCP para material de referencia más extenso, como la sintaxis de markdown, las formas de advertencia, la paginación de propiedades y ejemplos de update_data_source.

Páginas (20 herramientas)

Herramienta

Descripción

create_page

Crea una página a partir de markdown

create_page_from_file

Crea una página a partir de un archivo markdown local (solo stdio)

read_page

Lee una página como markdown

read_section

Lee una sección por nombre de encabezado

read_block

Lee un bloque por ID, incluidos los hijos anidados de los contenedores

read_toggle

Lee un toggle o un encabezado conmutable por título

search_in_page

Busca texto de bloque sin procesar en una página o en un toggle

append_content

Añade markdown a una página

replace_content

Reemplaza todo el contenido de la página de forma atómica (conserva los IDs de bloque de los bloques coincidentes)

update_section

Actualiza una sección por nombre de encabezado; reemplazo opcional del cuerpo que conserva el encabezado (destructivo; usa duplicate_page primero para contenido irremplazable)

update_toggle

Actualiza el cuerpo de un toggle por título (destructivo; conserva el ID del contenedor del toggle)

archive_toggle

Archiva un toggle o un encabezado conmutable por título

restore_toggle

Restaura un toggle o un encabezado conmutable archivado por ID de bloque archivado

find_replace

Busca y reemplaza texto, conservando archivos

update_block

Actualiza un solo bloque por ID (conserva la identidad del bloque para enlaces profundos y comentarios)

update_page

Actualiza el título, el icono o la portada

duplicate_page

Copia una página y su contenido

archive_page

Mueve una página a la papelera

move_page

Mueve una página a un nuevo padre

restore_page

Restaura una página archivada

Las herramientas destructivas admiten dry_run: true como comprobación previa. El modo dry-run no sube ni valida las subidas de markdown locales file:// porque eso crearía subidas en Notion; usa URLs HTTPS o ejecuta sin dry-run para archivos locales. El dry-run de replace_content traduce el markdown y devuelve advertencias del traductor, pero no puede mostrar los campos unmatched_blocks o truncated del lado de Notion porque no llama al endpoint de actualización de Notion.

restore_toggle está basado intencionadamente en ID: pasa el ID del bloque archivado devuelto por archive_toggle. Notion no expone la enumeración de hijos archivados para la búsqueda por título ni un flujo de trabajo read_page include_archived, por lo que restaurar por título no está disponible.

Navegación (3 herramientas)

Herramienta

Descripción

list_pages

Lista las páginas hijas bajo un padre, con created_time y last_edited_time por fila

search

Busca páginas y bases de datos

share_page

Obtiene la URL compartible

Cada fila de list_pages devuelve id, title, created_time y last_edited_time, de modo que un agente puede distinguir las páginas activas de las obsoletas sin una ida y vuelta por página. Las marcas de tiempo provienen directamente de Notion, redondeadas al minuto, y last_edited_time avanza con las ediciones de contenido y propiedades de la página. Ten en cuenta la diferencia deliberada con search, que devuelve last_edited solo como fecha, mientras que list_pages devuelve last_edited_time como una marca de tiempo ISO-8601 completa.

Bases de datos (9 herramientas)

Herramienta

Descripción

create_database

Crea una base de datos con esquema tipado

update_data_source

Actualiza el esquema de la base de datos (añadir, renombrar o eliminar propiedades; cambiar el título; mover a la papelera o restaurar)

get_database

Obtiene el esquema de la base de datos, los nombres de propiedades y las opciones

list_databases

Lista todas las bases de datos a las que la integración puede acceder

query_database

Consulta con filtros, ordenaciones o búsqueda de texto

add_database_entry

Añade una fila usando pares clave-valor simples

add_database_entries

Añade varias filas en una sola llamada

update_database_entry

Actualiza una fila usando pares clave-valor simples

delete_database_entry

Elimina (archiva) una entrada de base de datos

Las herramientas de escritura en bases de datos rechazan nombres de propiedades desconocidos y tipos de propiedades no admitidos con un error claro en lugar de descartarlos silenciosamente. Llama primero a get_database para confirmar los nombres y tipos de propiedades. Tipos de propiedad admitidos para escrituras: title, rich_text, number, select, multi_select, date, checkbox, url, email, phone, status, relation, people. Para people, pasa una cadena de ID de usuario única o un array de IDs de usuario. Los tipos calculados (formula, rollup, unique_id, created_time, last_edited_time, created_by, last_edited_by) los rellena Notion y no se pueden establecer mediante la API. Las escrituras de valores también se rechazan para files, verification, place, location y button. Para escrituras de relaciones, pasa una cadena de ID de página única ("Projects": "page-id") o un array ("Projects": ["id-a", "id-b"]); un array vacío limpia la relación.

easy-notion-mcp obtiene el esquema de la base de datos, asigna los valores al formato de propiedades de Notion y gestiona la conversión de tipos automáticamente cuando los agentes pasan pares clave-valor simples como { "Status": "Done" }. El esquema se almacena en caché durante 5 minutos para evitar llamadas redundantes a la API durante operaciones por lotes.

Vistas (6 herramientas)

Herramienta

Descripción

list_views

Lista las vistas guardadas de una base de datos o fuente de datos

get_view

Obtiene la configuración sin procesar de una vista guardada

query_view

Consulta entradas a través de una vista guardada

create_view

Crea una vista de tabla, lista, tablero, calendario, galería o línea de tiempo

update_view

Renombra o actualiza los campos sin procesar de filtro/ordenación/configuración de una vista guardada

delete_view

Elimina una vista guardada con confirmación explícita

Comentarios (2 herramientas)

Herramienta

Descripción

list_comments

Lista los comentarios de una página

add_comment

Añade un comentario a una página

Usuarios (2 herramientas)

Herramienta

Descripción

list_users

Lista los usuarios del espacio de trabajo

get_me

Obtiene el usuario bot actual

Servidor (1 herramienta)

Herramienta

Descripción

get_config

Informa de la configuración del propio servidor: versión, transporte, raíz del espacio de trabajo y número de herramientas visibles

get_config es la herramienta a la que recurrir cuando un error de ruta de archivo o de configuración te deja sin pistas. create_page_from_file solo acepta rutas dentro de la raíz del espacio de trabajo y, cuando una ruta queda fuera de ella, el rechazo ahora indica la raíz resuelta. get_config te permite leer esa raíz directamente en lugar de deducirla. En modo HTTP, la raíz del espacio de trabajo no aplica, por lo que los campos de ruta son null y el estado es not_applicable; el servidor nunca informa de rutas del host a los llamadores HTTP.

¿Qué recursos MCP están disponibles?

Los clientes que admiten Recursos MCP pueden leer estos documentos bajo demanda sin cargar todo el material de referencia en cada descripción de herramienta:

URI del recurso

Contenido

easy-notion://docs/markdown

Sintaxis de markdown admitida para escrituras y lecturas de páginas

easy-notion://docs/warnings

Códigos de advertencia y formas de respuesta

easy-notion://docs/property-pagination

Comportamiento de max_property_items para propiedades largas

easy-notion://docs/update-data-source

Modos de payload de update_data_source, ejemplos y notas de seguridad del esquema

¿Qué tipos de bloques admite easy-notion-mcp?

easy-notion-mcp admite 24 tipos de bloques de Notion utilizando sintaxis de markdown estándar ampliada con convenciones para bloques específicos de Notion como toggles, columnas y callouts. Los agentes escriben markdown familiar — easy-notion-mcp gestiona la conversión hacia y desde el formato de bloques de Notion.

Markdown estándar

Sintaxis

Markdown

Encabezados

# H1 ## H2 ### H3

Negrita, cursiva, tachado

**bold** *italic* ~~strike~~

Código en línea

`code`

Enlaces

[text](url)

Imágenes

![alt](url)

Lista con viñetas

- item

Lista numerada

1. item

Lista de tareas

- [ ] todo / - [x] done

Cita en bloque

> text

Bloque de código

```language

Tabla

Sintaxis estándar de tabla con tuberías

Divisor

---

Sintaxis específica de Notion

Bloque

Sintaxis

Alternancia

+++ Title ... +++

Columnas

::: columns / ::: column ... :::

Llamada (nota)

> [!NOTE]

Llamada (consejo)

> [!TIP]

Llamada (advertencia)

> [!WARNING]

Llamada (importante)

> [!IMPORTANT]

Llamada (información)

> [!INFO]

Llamada (éxito)

> [!SUCCESS]

Llamada (error)

> [!ERROR]

Ecuación

$$expression$$

Tabla de contenido

[toc]

Incrustar

[embed](url)

Marcador

URL desnuda en su propia línea

Subida de archivo (imagen)

![alt](file:///path/to/image.png)

Subida de archivo (archivo)

[name](file:///path/to/file.pdf)

Saltos de línea y collapse_soft_wraps

Por defecto, un solo salto de línea dentro de un párrafo se escribe tal cual. Por lo tanto, el markdown con saltos de línea forzados a una columna fija (la convención en la mayoría de los repositorios) llega a Notion con esos saltos de línea. Ese comportamiento predeterminado no ha cambiado.

Toda herramienta de escritura de markdown acepta un collapse_soft_wraps: true opcional, que aplica en su lugar la semántica de soft-wrap de CommonMark: un solo salto de línea dentro de un párrafo se convierte en un espacio, de modo que un archivo con saltos de línea forzados llega como párrafos fluidos. Las líneas en blanco siguen separando bloques y los bloques de código delimitados no se modifican en ninguno de los dos modos.

easy-notion page create-from-file --title "Design notes" --file ./NOTES.md --collapse-soft-wraps

No lo uses al volver a subir contenido que hayas leído desde Notion, o se perderán los saltos de línea intencionados.

Los saltos de línea forzados explícitos (una barra invertida final o dos espacios finales) se comportan de forma idéntica se establezca o no la opción, pero difieren según la ruta de escritura:

Ruta de escritura

Comportamiento del salto de línea forzado

create_page, create_page_from_file, append_content, update_section, update_toggle, update_block

Se mantiene dentro del bloque

replace_content

La importación de Markdown mejorado de Notion representa un salto de línea dentro de un párrafo como un párrafo separado, por lo que un salto forzado llega como una división de párrafo

Esa diferencia es una propiedad de la ruta de importación, no de collapse_soft_wraps.

Duplicación del título y del H1 inicial

create_page y create_page_from_file aceptan un strip_leading_h1: true opcional, que elimina el H1 inicial del documento para que un archivo que comienza con el mismo encabezado que pasas como title no ponga ese encabezado dos veces en la página. Solo se aplica cuando el primer bloque de nivel superior convertido es un heading_1 simple (no alternable), y su valor predeterminado es false.

easy-notion page create-from-file --title "Design notes" --file ./NOTES.md --strip-leading-h1

create_page, create_page_from_file, append_content, replace_content, update_section y update_toggle aceptan return_block_map: false para omitir block_map cuando no se necesita; el valor predeterminado sigue siendo true y no cambia.

¿Puedo leer y reescribir páginas conservando el formato?

Sí, para las convenciones de markdown que este servidor representa. El soporte de ida y vuelta cubre 24 tipos de bloques. Las omisiones y degradaciones conocidas están documentadas, y muchas se notifican con advertencias explícitas.

read_page devuelve las convenciones de markdown que create_page acepta: encabezados, listas, tablas, destacados, conmutadores, columnas, ecuaciones y menciones de página.

Cuando una página contiene tipos de bloques de Notion que este servidor aún no representa, como synced_block, child_database, child_page o link_to_page, read_page incluye un campo warnings con el código omitted_block_types que enumera los IDs y tipos de bloques omitidos. Escribir ese markdown de vuelta mediante replace_content eliminaría esos bloques, por lo que la advertencia permite a los agentes evitar reescrituras inseguras. Para una mención de página en línea, use @[Title](notion-url), que es una construcción separada del tipo de bloque link_to_page.

Los bloques de notas de reuniones de Notion AI (y la obsoleta transcription) se representan como un conmutador sintético que contiene el título, una marca de tiempo de grabación opcional y secciones ## Summary / ## Notes; las transcripciones se incluyen solo con read_page include_transcript: true. Estas lecturas renderizadas emiten una advertencia read_only_block_rendered para señalar que escribir el markdown de vuelta reemplaza el bloque de reunión nativo con bloques ordinarios.

Algunas degradaciones no se notifican con una advertencia. En la ruta de replace_content, los marcadores y las incrustaciones se escriben como URL simples (estas sí advierten), mientras que los bloques file, audio y video se reducen a sus URL silenciosamente. Las anotaciones de subrayado y texto de color no se representan en markdown y se eliminan silenciosamente al leer y al escribir.

easy-notion-mcp permite a los agentes leer una página, modificar la cadena de markdown y escribirla de nuevo conservando el formato, la estructura y el contenido admitidos. Sin traducción de formato. Sin reconstrucción de bloques. Los agentes editan páginas de Notion de la misma manera que editan código, como texto.

¿Cuál es la diferencia entre find_replace y replace_content?

easy-notion-mcp ofrece tres estrategias de edición para diferentes casos de uso:

  • replace_content — Reemplaza todo el contenido de una página con nuevo markdown. Ideal para reescrituras completas.

  • update_section — Reemplaza una sola sección identificada por el nombre del encabezado. Por defecto, el markdown de reemplazo incluye el encabezado y reemplaza la sección completa. Pase preserve_heading: true (o CLI --preserve-heading) para mantener el ID del bloque de encabezado existente, el texto, el tipo, los comentarios y el estado conmutable, mientras reemplaza destructivamente solo el cuerpo de la sección.

  • find_replace — Busca y reemplaza texto específico en cualquier parte de la página, conservando todo el demás contenido y los archivos adjuntos. Ideal para ediciones quirúrgicas.

Pase dry_run: true en las herramientas MCP, o --dry-run en la CLI, antes de ediciones destructivas cuando desee una respuesta de verificación previa en lugar de una mutación.

¿Cómo maneja easy-notion-mcp las bases de datos?

easy-notion-mcp proporciona 9 herramientas de base de datos que abstraen el complejo formato de propiedades de Notion. Los agentes pasan pares clave-valor simples como { "Status": "Done", "Priority": "High" }; easy-notion-mcp obtiene el esquema de la base de datos en tiempo de ejecución, lo almacena en caché durante 5 minutos y lo convierte automáticamente al formato de propiedades de Notion.

easy-notion-mcp admite crear y actualizar bases de datos con esquemas tipados, consultar con filtros y ordenamientos, y operaciones masivas mediante add_database_entries (múltiples filas en una sola llamada).

Recetario: recetas para tu propio agente

Estas recetas apuntan a tu propio agente hacia Notion. El agente posee la inteligencia; easy-notion-mcp proporciona tejido conectivo determinista a través de las herramientas MCP existentes, por lo que las recetas se ejecutan bajo demanda sin una segunda instalación. Son gratuitas y soberanas: tu propio agente, tu propio token, configuración de token de API sin OAuth y consultas de base de datos en el plan gratuito.

Estos pasos funcionan a través de las herramientas MCP o del conector claude.ai cuando las herramientas equivalentes están habilitadas. La Receta 2 también funciona a través de la habilidad CLI easy-notion en skills/easy-notion-cli/; la Receta 1 necesita create_database, búsqueda de bloques fuente con search_in_page y un filtro estructurado de deduplicación, y la superficie CLI actual no expone ese flujo completo. Los agentes de Claude Code pueden usar la habilidad operativa en skills/notion-recipes/.

Receta 1: notas de reunión a elementos de acción

Esta receta convierte una página de notas de reunión o notas pegadas en filas deduplicadas en una base de datos de Elementos de Acción. La secuencia de herramientas es create_database una vez, luego por ejecución read_page cuando la fuente es una página, search_in_page para resolver el ID de bloque fuente de cada elemento, query_database con un filtro exacto de Item Key para cada elemento candidato, add_database_entry o add_database_entries para nuevas filas, y una verificación final con query_database.

El resultado real probado fue de 5 filas de una reunión de planificación. Los propietarios y fechas de vencimiento faltantes se almacenaron en la selección múltiple Flags, no en Source, y un filtro de query_database de {"property":"Item Key","rich_text":{"equals":"38bbe876-242f-81f1-97b7-df935d050a24:38bbe876-242f-81c9-86c6-d9a792fc70b7"}} devolvió exactamente 1 fila. Ejecutar dos veces sobre las mismas notas dejó el recuento en 5 con cero duplicados. Una búsqueda de texto libre para el nombre de reunión compartido devolvió todas las filas porque también escaneó Source, por lo que esta receta usa el filtro exacto de Item Key para la deduplicación.

Límite de seguridad: la Receta 1 es segura de re-ejecutar e idempotente porque Item Key almacena la identidad estable de Notion de la línea fuente (<pageId>:<blockId>), no el texto de la acción.

Copiar y pegar para usuarios del conector claude.ai, Receta 1

Use the enabled easy-notion or Notion connector tools to turn my meeting notes into an Action Items database.

Note: the simple {"Property":"Value"} write format below assumes the easy-notion tools. If only the official Notion connector is enabled, wrap each value in its Notion property-type object instead.

Inputs I will provide:
- Meeting notes page or pasted meeting notes: <MEETING_NOTES_PAGE_OR_TEXT>
- Parent page for the database, if a new database is needed: <PARENT_PAGE>
- Existing Action Items database, if one already exists: <DATABASE_NAME_OR_ID>

If an Action Items database does not already exist, create one with these properties:
- Name: title
- Item Key: rich_text
- Owner: rich_text
- Due: date
- Status: status
- Flags: multi_select
- Source: rich_text

Read the meeting notes or use the pasted notes. Extract only discrete action items. For each item, derive:
- Name: the action text
- Owner: the named assignee, or blank
- Due: the stated date as ISO YYYY-MM-DD, or blank
- Item Key: the source line's stable identity, formatted as <sourcePageId>:<sourceBlockId>
- Source: the meeting title plus date, with no flags stashed here
- Status: Not started
- Flags: add needs-owner if no owner, and needs-due if no due date

Resolve sourceBlockId with search_in_page. read_page returns markdown without block IDs. For a Notion-page source, call read_page to extract items, then for each item call search_in_page with a verbatim, distinctive substring of that item's original source line. Use the matches[].block_id whose text is that source line. If several blocks match, use a longer verbatim substring to isolate one block. For pasted notes, first save them as a Notion page with create_page, then proceed through search_in_page. Do not rely on block IDs from create_page, which returns only {id,title,url}. If one source line contains multiple distinct actions, append a stable ordinal suffix in source order, such as :1 or :2, to keep keys unique.

Before inserting each item, dedupe with an exact Item Key filter:
{"property":"Item Key","rich_text":{"equals":"<that item's key>"}}

If the query returns no results, insert the row with simple key-value properties. If it returns a result, skip that item. Do not dedupe with free-text database search, because text search also scans Source and can false-match every row from the same meeting.

After inserting, query the database and summarize the rows created and skipped.

Re-running is safe and idempotent because the exact Item Key filter uses the source line's stable Notion identity, not the action wording.

Receta 2: edición masiva, buscar y reemplazar, y reparación

Esta receta cubre dos superficies donde un agente puede iterar más allá de los límites nativos de Notion: reparación de propiedades de base de datos y buscar y reemplazar en el cuerpo de la página. Para la reparación de base de datos, la secuencia es get_database, query_database a través de todas las filas, construir un mapa de normalización, update_database_entry para las filas que necesitan correcciones, y luego volver a consultar. Para el texto de la página, la secuencia es find_replace con dry_run: true, find_replace con replace_all: true, y luego read_page para verificar.

La reparación real probada de base de datos normalizó 4 filas con valores mixtos Eng y engineering a una opción consistente, dejando las filas no relacionadas sin cambios. La edición real probada de página reemplazó 4 ocurrencias en párrafos y un cuerpo de encabezado. Advertencia: la coincidencia de opciones de selección y estado no distingue entre mayúsculas y minúsculas, y las escrituras se ajustan a la capitalización de la opción existente más antigua. Si ya existe una variante en minúsculas, escribir una versión capitalizada reutiliza la opción en minúsculas existente. Para forzar una capitalización específica, renombre la opción en la interfaz de Notion en lugar de escribir la nueva capitalización.

Copiar y pegar para usuarios del conector claude.ai, Receta 2

Use the enabled easy-notion or Notion connector tools to repair Notion database rows or replace repeated text in a Notion page.

Note: the simple {"Property":"Value"} write format below assumes the easy-notion tools. If only the official Notion connector is enabled, wrap each value in its Notion property-type object instead.

Inputs I will provide:
- Target database for property repair: <DATABASE_NAME_OR_ID>
- Property to normalize: <PROPERTY_NAME>
- Normalization map, for example {"Eng":"Engineering","engineering":"Engineering"}
- Target page for find-replace, if needed: <PAGE_NAME_OR_ID>
- Find text and replacement text, if needed: <FIND_TEXT> -> <REPLACE_TEXT>

For database property repair:
1. Get the database schema so you know the exact property names. If select or status options are missing from the schema, query live rows and read the current values from the results.
2. Query the database rows. If the database is large, page through all results in a loop.
3. Build or use the normalization map I provide.
4. For each row whose property value needs fixing, update that row with a simple key-value map such as {"<PROPERTY_NAME>":"<CANONICAL_VALUE>"}.
5. Re-query the database and summarize how many rows changed and which values remain.

Important caveat: select and status option matching is case-insensitive, and writes snap to the earliest-existing option's casing. If a lowercase variant already exists, writing a capitalized version may reuse the lowercase option. To force specific casing, I need to rename the option in Notion's UI.

For page-body find-replace:
1. Run a dry-run find-replace with replace_all enabled and report the match count before changing anything.
2. If the match count is expected, run find-replace with replace_all enabled.
3. Read the page afterward and verify the replacement.

¿Qué pasa con la seguridad y la inyección de prompts?

easy-notion-mcp incluye dos capas de seguridad para implementaciones en producción:

Endurecimiento contra inyección de prompts: Las respuestas de lectura en markdown (read_page, read_section, read_block y read_toggle) incluyen un prefijo de aviso de contenido que instruye al agente a tratar los datos de Notion como contenido, no como instrucciones. search_in_page devuelve fragmentos/texto sin procesar que deben tratarse de la misma manera. Esto reduce el riesgo de que el contenido de la página dirija el comportamiento del agente; el comportamiento final depende del modelo y del cliente. Establezca NOTION_TRUST_CONTENT=true para deshabilitar el aviso de markdown si usted controla el espacio de trabajo.

Saneamiento de URL: javascript:, data: y otros protocolos de URL inseguros se eliminan y se representan como texto plano. Solo se permiten http:, https: y mailto:.

Estabilidad y versionado

easy-notion-mcp sigue Versionado Semántico. A partir de 1.0.0, el contrato público está congelado solo aditivo: los nombres de herramientas, los esquemas de entrada de herramientas, las formas de retorno de herramientas, las convenciones de markdown personalizadas y el vocabulario de códigos de advertencia no cambiarán de manera incompatible hasta una futura versión 2.0. Los cambios aditivos (nuevas herramientas, nuevos parámetros opcionales, nuevos campos de respuesta opcionales, nuevos códigos de advertencia) no son incompatibles y pueden incluirse en versiones menores.

Dos superficies están fuera de esta congelación: el contrato de autenticación OAuth / HTTP es experimental y puede cambiar mientras su postura de seguridad madura, y la CLI easy-notion es pre-1.0 y aún no está cubierta. Consulte el CHANGELOG para la declaración completa del contrato y el historial por versión.

Preguntas frecuentes

¿En qué se diferencia easy-notion-mcp del servidor MCP oficial de Notion?

El paquete npm oficial de Notion MCP (@notionhq/notion-mcp-server) es un proxy de API sin procesar que devuelve JSON de Notion sin modificar, por lo que leer una página cuesta aproximadamente 6–7× más tokens de respuesta que el markdown de easy-notion-mcp. easy-notion-mcp convierte todo a markdown GFM estándar que los agentes ya conocen, admite 24 tipos de bloques con advertencias documentadas de ida y vuelta, e incluye endurecimiento contra inyección de prompts. Notion también ofrece un servidor MCP remoto alojado separado (basado en OAuth) que utiliza un formato de markdown personalizado basado en etiquetas HTML, mientras que easy-notion-mcp utiliza sintaxis de markdown estándar.

¿Con qué clientes MCP funciona easy-notion-mcp?

easy-notion-mcp funciona con cualquier cliente compatible con MCP, incluidos Claude Desktop, Claude Code, Cursor, VS Code Copilot, Windsurf y OpenClaw. Admite tanto transporte stdio (token de API) como transporte HTTP (OAuth). Consulte las instrucciones de configuración para obtener configuraciones copiables para cada cliente.

¿Admite easy-notion-mcp la carga de archivos?

Sí. easy-notion-mcp admite la carga de archivos usando el protocolo file:/// en sintaxis de markdown. Suba imágenes con ![alt](file:///path/to/image.png) y archivos con [name](file:///path/to/file.pdf).

¿Maneja easy-notion-mcp contenido anidado y complejo?

Sí. Los conmutadores anidados dentro de conmutadores, columnas con tipos de contenido mixtos (listas, citas en bloque y bloques de código en diferentes columnas), listas anidadas con viñetas y numeradas, y soporte completo de unicode, incluidos japonés, chino, ruso, árabe y emoji, están cubiertos por pruebas de ida y vuelta para estas formas admitidas.

¿Maneja easy-notion-mcp fallos parciales en operaciones por lotes?

Sí. add_database_entries devuelve matrices separadas succeeded y failed. Si una entrada falla la validación, las demás aún se crean. Los agentes pueden reintentar solo los fallos sin reenviar todo el lote.

Comunidad

Hay un Discord comunitario en discord.gg/S8cghJSVBU. El canal #easy-notion-mcp cubre preguntas de configuración y discusión de diseño, y el resto del servidor está abierto para mostrar y contar o conversación general. Para errores y solicitudes de funciones concretas, GitHub issues sigue siendo el canal canónico.

Contribuciones

Se aceptan issues y PRs en GitHub.

Licencia

MIT

Available Tools

43 tools
add_commentA

Add a comment to a page. Supports inline markdown and page mentions with @Title. Unlike append_content, a mention the integration cannot resolve is not downgraded to a plain link and returns no warning, so the call can fail. Returns { id, content }.

Inputs: text (required), page_id (required), collapse_soft_wraps.

add_database_entriesA

Create multiple entries in a database in one call. Each entry uses the same simple key-value format as add_database_entry. Returns per-entry results — partial failures don't block the batch.

Inputs: entries (required), page_id, database_id.

add_database_entryA

Create one database entry using simple key-value property inputs. Call get_database first to see available property names and valid select/status options.

Writable property values use simple inputs:

  • title, rich_text: string

  • number: number

  • select, status: option name string

  • multi_select: array of option name strings

  • date: ISO date string (start only)

  • checkbox: boolean

  • url, email, phone: string

  • relation: string or array of page IDs

  • people: string or array of user IDs

Not writable from this tool:

  • formula, rollup, unique_id, created_time, last_edited_time, created_by, last_edited_by: computed by Notion

  • files, verification, place, location, button: not supported for value writes here

Example: { "Name": "Buy groceries", "Status": "Todo", "Priority": "High", "Due": "2025-03-20", "Tags": ["Personal"] }.

Inputs: properties (required), page_id, database_id.

append_contentA

Append markdown content to an existing page. The server converts markdown into native Notion blocks, not flat/plain text. The server automatically handles Notion API limits: batches more than 100 child blocks, splits rich text over 2000 characters, and writes deeply nested blocks in additional passes, so callers can append large documents in one call with no need to pre-chunk or pre-split. Supports the same syntax as create_page; read resource easy-notion://docs/markdown for the full syntax guide. Page mentions: @Title; a mention the integration cannot resolve is downgraded to a plain link and reported with a mention_target_unresolved warning. Returns: { success: true, blocks_added: }, plus block_map for top-level appended blocks when present and warnings when present.

Inputs: page_id (required), markdown (required), return_block_map, collapse_soft_wraps.

archive_pageC

Archive a page in Notion.

Inputs: page_id (required), dry_run.

archive_toggleA

Archive one toggle by title from a page. Searches recursively and matches plain toggle blocks plus toggleable heading_1, heading_2, and heading_3 blocks using case-insensitive trimmed text. Archives the matched container block; children are not deleted individually. Missing titles return the available toggle titles.

Inputs: title (required), page_id (required), dry_run.

create_databaseA

Create a database under a parent page.

Supported property types and extras:

  • title

  • rich_text (alias: text)

  • number (optional: format, for example "dollar", "percent", "number_with_commas")

  • select, multi_select, status (optional: options array of strings or {name, color, description})

  • date, checkbox, url, email, phone

  • formula (required: expression, for example "prop("Count") * 2")

  • rollup (required: function, relation_property, rollup_property)

  • relation (required: data_source_id; optional: relation_type "single_property" or "dual_property", synced_property_name)

  • unique_id (optional: prefix, for example "ENG")

  • people, files

  • created_time, last_edited_time, created_by, last_edited_by

  • verification, place, location, button

Unknown property types fail with an explicit error. No silent drops.

Inputs: title (required), schema (required), parent_page_id (required), is_inline.

create_pageA

Create a Notion page from markdown as native Notion blocks. Server handles 100-block batching, 2000-char splitting, and deep nesting, so no pre-chunking. Supports stdio-only file:// uploads. Syntax: easy-notion://docs/markdown. Mentions: @Title. Returns { id, title, url, success: true }, note for workspace-parent pages, plus block_map for top-level created blocks when present.

Inputs: title (required), markdown (required), icon, cover, +4 more.

create_page_from_fileA

Create a Notion page from a local markdown file. The server reads and validates the file, then creates the same result as create_page without sending file contents through the agent context. The server converts the markdown to native Notion blocks (not flat text) and automatically handles Notion's limits (100-block batching, 2000-char splitting, deep nesting), so large files need no pre-chunking.

STDIO MODE ONLY. This tool is not available when the server runs over HTTP, because in HTTP mode the server's filesystem belongs to the server host, not the caller.

Restrictions:

  • file_path must be an ABSOLUTE path (no relative paths, no ~ expansion)

  • File must be inside the configured workspace root (defaults to the server's process.cwd(); override via the NOTION_MCP_WORKSPACE_ROOT env var)

  • File extension must be .md or .markdown

  • File size must be ≤ 1 MB (1,048,576 bytes)

  • File must be valid UTF-8

  • Symlinks are resolved and the resolved path must still be inside the workspace root

For supported markdown syntax, read resource easy-notion://docs/markdown. Page mentions: @Title. Returns: { id, title, url, success: true }, plus note only when created as a private workspace page, plus block_map for top-level created blocks when present.

Inputs: title (required), file_path (required), parent_page_id, return_block_map, +2 more.

create_viewA

Create a Notion database view. Pass database_id. Dashboard views and dashboard widget placement are not supported.

Inputs: name (required), type (required), database_id (required), sorts, +4 more.

delete_database_entryB

Delete (archive) a database entry.

Inputs: page_id (required), dry_run.

delete_viewA

Delete a Notion database view. Destructive: confirm must be exactly true.

Inputs: view_id (required), confirm, dry_run.

duplicate_pageA

Duplicate a page. Reads all blocks from the source and creates a new page with the same content that this server can represent. If the source contains block types this server does not yet support (e.g. child_page subpages, synced_block, child_database, link_to_page), those are omitted from the duplicate AND listed in a warnings field with code omitted_block_types. Notion AI meeting notes are duplicated as ordinary toggle/heading/paragraph blocks (summary and notes only — transcripts are not duplicated); a read_only_block_rendered warning is emitted to identify meeting-notes blocks whose native identity was not preserved across the duplicate. Deep-duplication of subpages is not yet supported.

Inputs: page_id (required), title, parent_page_id.

find_replaceA

Find and replace text on a page. Preserves uploaded files and blocks that aren't touched. More efficient than replace_content for targeted text changes like fixing typos, updating URLs, or renaming terms.

Inputs: find (required), page_id (required), replace (required), dry_run, +1 more.

get_configA

Report this server's own settings: version, transport, the workspace root that bounds create_page_from_file file paths, and how many tools are visible. Call this when a file-path or configuration error occurs and you need the server's actual settings rather than a guess. Read-only, makes no Notion API call, and never returns credentials. Returns { version, transport, workspace_root_configured, workspace_root_resolved, workspace_root_status, workspace_root_source, markdown_docs, visible_tools_count }.

Inputs: no named parameters.

get_databaseA

Get a database's schema — property names, types, and select/status options. Call this before query_database or add_database_entry to know the exact property names and valid values.

Inputs: page_id, database_id.

get_meA

Get the current bot user.

Inputs: no named parameters.

get_viewA

Retrieve one Notion database view by ID. Returns a curated summary (id, name, type, url, data_source_id); set include_config: true for the full raw Notion view object.

Inputs: view_id (required), include_config.

list_commentsB

List comments on a page.

Inputs: page_id (required).

list_databasesA

List all databases the integration can access. Returns database names and IDs — use get_database on any result to see its schema.

Inputs: no named parameters.

list_pagesA

List child pages under a parent page. Each row returns id, title, created_time, and last_edited_time. Timestamps are full ISO-8601 values from Notion, rounded to the minute, and last_edited_time advances on page content and property edits.

Inputs: parent_page_id (required).

list_usersB

List workspace users.

Inputs: no named parameters.

list_viewsA

List Notion database views. Pass exactly one of database_id or data_source_id. Returns a curated summary of each view (id, name, type, url, data_source_id) plus pagination cursors; set include_config: true for the full raw Notion view objects.

Inputs: page_size, database_id, start_cursor, data_source_id, +1 more.

move_pageB

Move a page to a new parent page.

Inputs: page_id (required), new_parent_id (required).

query_databaseA

Query a database with optional filters, sorts, or text search. Use text for simple keyword search across title, rich_text, url, email, and phone fields. For advanced filters, pass Notion filter syntax and call get_database first to see property names and valid options.

Response shape: { results: Array, warnings?: Array }. Multi-value properties are capped by max_property_items and can emit truncated_properties; read resources easy-notion://docs/property-pagination and easy-notion://docs/warnings for details.

Inputs: text, sorts, filter, page_id, +2 more.

query_viewB

Query a Notion database view. Creates a temporary view query, fetches database row results, then deletes the query.

Inputs: view_id (required), page_size, start_cursor.

read_blockA

Read one block by ID as markdown. Container blocks are fetched recursively with children. Unsupported root block types return a clear error; unsupported nested blocks are omitted and listed in warnings. Notion AI meeting-notes blocks encountered in the result are rendered as a synthetic toggle and produce a read_only_block_rendered warning. Transcripts are not included from these tools.

Inputs: block_id (required).

read_pageA

Read a page and return metadata plus markdown. Recursively fetches nested blocks and uses the same markdown conventions accepted by create_page. If unsupported block types are omitted from the markdown, they are listed in warnings. Do NOT round-trip markdown through replace_content when omitted_block_types warnings are present; omitted blocks would be deleted.

Notion AI meeting notes are rendered as a synthetic toggle containing the title, an optional recording timestamp callout, and ## Summary / ## Notes heading sections. Transcript sections are included only with include_transcript: true. A read_only_block_rendered warning is emitted whenever such a block is rendered, indicating that round-tripping the markdown through replace_content will replace the native meeting-notes block with ordinary blocks.

Note on max_blocks: the cap counts top-level page blocks only; section descendants of meeting-notes blocks are fetched in full regardless of the cap, consistent with how nested children of normal blocks are fetched.

Long titles are paginated with max_property_items. For markdown conventions, warning shapes, and pagination details, read resources easy-notion://docs/markdown, easy-notion://docs/warnings, and easy-notion://docs/property-pagination.

Inputs: page_id (required), max_blocks, include_metadata, include_transcript, +1 more.

read_sectionA

Read a single page section by heading name. Uses the same heading matching and boundary rules as update_section: headings are matched case-insensitively, H1 sections end at the next heading of any level, and H2/H3 sections end at the next heading of the same or higher level. Includes the heading block itself and recursively renders nested children only for blocks inside the selected section. If unsupported nested block types are omitted, the response includes warnings. Notion AI meeting-notes blocks encountered in the result are rendered as a synthetic toggle and produce a read_only_block_rendered warning. Transcripts are not included from these tools.

Inputs: heading (required), page_id (required).

read_toggleA

Read one toggle by title from a page. Searches recursively and matches plain toggle blocks plus toggleable heading_1, heading_2, and heading_3 blocks using case-insensitive trimmed text. Missing titles return the available toggle titles. Notion AI meeting-notes blocks encountered in the result are rendered as a synthetic toggle and produce a read_only_block_rendered warning. Transcripts are not included from these tools.

Inputs: title (required), page_id (required).

replace_contentA

Replaces all page content with the provided markdown atomically (one Notion API call). Notion's atomic markdown endpoint converts the markdown to native Notion blocks in that one API call. On matched blocks Notion preserves the original block IDs, so deep-link anchors (#block-id) and inline-comment threads attached to those blocks survive the edit. Unmatched blocks (returned in warnings with code unmatched_blocks) are replaced with new IDs.

NOT preserved across replace_content: child_page subpages, synced_block instances, child_database views, and link_to_page references on the source page. Enhanced Markdown has no input form for these, so they are dropped from the new page content. If the source contains them, use duplicate_page first or edit those types via the Notion UI. For an inline page mention, use @Title; that is a separate construct from the link_to_page block type.

Bookmarks and embeds are written as bare URLs (Notion auto-links) and surface a bookmark_lost_on_atomic_replace or embed_lost_on_atomic_replace warning so callers know the rich preview is lost. For supported markdown syntax and warning details, read resources easy-notion://docs/markdown and easy-notion://docs/warnings. Returns: { success: true }, optionally truncated: true, optionally warnings with entries such as { code: "unmatched_blocks", block_ids: [...] }, plus block_map for the resulting top-level blocks when present. A dry run returns { success: true, dry_run: true, operation, page_id, would_update: true } and optionally warnings.

Inputs: page_id (required), markdown (required), dry_run, return_block_map, +1 more.

restore_pageA

Restore an archived page.

Inputs: page_id (required).

restore_toggleA

Restore an archived toggle or toggleable heading by archived block ID. Use the block ID returned by archive_toggle; Notion does not expose archived child enumeration for title search or read_page include_archived.

Inputs: block_id (required), dry_run.

search_in_pageA

Search raw Notion block plain text inside a page, optionally scoped to one toggle or toggleable heading by title. Matching is case-insensitive plain substring search.

Inputs: query (required), page_id (required), within_toggle.

share_pageA

Return the page URL that can be shared from Notion.

Inputs: page_id (required).

update_blockA

Update a single block in place by ID. Preserves the block's identity (deep-link anchors and inline-comment threads attached to the block survive the edit). Use this for surgical edits: fixing a heading, toggling a checkbox, rewriting one paragraph. For multi-block edits, use append_content, replace_content, or update_section.

Type lock-in: the markdown must parse to the same block type as the existing block. update_block cannot change a block's type, because Notion's API forbids it. To change a block's type, use replace_content or delete + append.

Updatable types: paragraph, heading_1, heading_2, heading_3, toggle, bulleted_list_item, numbered_list_item, quote, callout, to_do, code, equation. Container blocks (toggle, callout) update first-level content only, and children stay untouched. Non-updatable types (divider, table, image, bookmark, etc.) accept only archived: true to delete the block. Page mentions: @Title.

To delete a block, pass archived: true instead of markdown. Exactly one of markdown or archived is required.

Inputs: block_id (required), checked, dry_run, archived, +2 more.

update_database_entryA

Update an existing database entry using simple key-value property inputs. Pass only properties to change; omitted properties are left unchanged. Call get_database first to see available property names and valid select/status options.

Writable property values use the same simple inputs as add_database_entry:

  • title, rich_text: string

  • number: number

  • select, status: option name string

  • multi_select: array of option name strings

  • date: ISO date string (start only)

  • checkbox: boolean

  • url, email, phone: string

  • relation: string or array of page IDs

  • people: string or array of user IDs

Not writable from this tool:

  • formula, rollup, unique_id, created_time, last_edited_time, created_by, last_edited_by: computed by Notion

  • files, verification, place, location, button: not supported for value writes here

Inputs: page_id (required), properties (required).

update_data_sourceA

CRITICAL: full-list semantics. When you update a select or status property's options array, you MUST send the full desired list. Any existing option you omit will be permanently removed from the database, along with any relationship to rows currently using it. Rows that currently reference a removed option are silently reassigned to the default group's first option (for example "Not started" for status properties). No signal is raised. If you want to preserve the meaning of existing rows when removing an option, reclassify those rows to another explicit option before removing the option from the schema. To add one option, first call get_database, then resend the full current list with your addition appended.

Cannot toggle is_inline on existing databases. is_inline is a database-level field, not a data-source field. A separate update_database tool may be added later.

Updates a database's schema: rename properties, add or update property definitions, remove properties, change the title, or move it to/from trash. Use after get_database. Supports raw Notion payloads and schema helper payloads; read resource easy-notion://docs/update-data-source for modes, examples, status notes, and limitations. At least one of title, properties, or in_trash must be provided.

Inputs: title, page_id, in_trash, properties, +1 more.

update_pageA

Update page title, icon, or cover. Cover accepts an image URL, or a file:// path (stdio transport only) which will be uploaded to Notion. In HTTP transport, the file:// form is rejected — use an HTTPS URL instead.

Inputs: page_id (required), icon, cover, title.

update_sectionA

DESTRUCTIVE, no rollback: this tool deletes blocks in the section, then writes new blocks. If the write fails mid-call, the section is left partially or fully emptied; for most sections the heading anchor is deleted, so a retry can fail with "heading not found." For irreplaceable sections, duplicate_page the target first so you have a restore point.

Update a section of a page by heading name. Finds the heading, replaces everything from that heading to the next section boundary. For H1 headings, the section extends to the next heading of any level. For H2/H3 headings, it extends to the next heading of the same or higher level. Include the heading itself in the markdown. If the section starts at the first block, the replacement markdown must start with the same heading type so following sections stay in place. With preserve_heading:true, the existing heading block ID, text, type, comments, and toggleable state are preserved, but the section body blocks and existing toggleable-heading children are still destructively replaced; replacement markdown is treated as body-only, and a leading matching heading is stripped for compatibility. More efficient than replace_content for editing one section of a large page. Page mentions: @Title. Returns { deleted, appended }, plus deleted_blocks for the deleted top-level blocks when present and block_map for the top-level appended blocks when present. A dry run instead returns { success: true, dry_run: true, operation, page_id, heading, target_block_id, target_block_type, preserve_heading, deleted, appended, would_delete_block_ids, append_parent_id }, plus append_after_block_id when the append is anchored to a preceding block, and would_update with would_update_block_id when the heading block itself is rewritten.

Inputs: heading (required), page_id (required), markdown (required), dry_run, +3 more.

update_toggleA

DESTRUCTIVE, no rollback: this tool preserves the matched toggle container block ID, then deletes its body children and appends replacement body blocks. Child block IDs inside the body change, and if the write fails mid-call the toggle can be left partially or fully emptied. For irreplaceable content, duplicate_page the target first so you have a restore point.

Update the body of one toggle by title from a page. Searches recursively and matches plain toggle blocks plus toggleable heading_1, heading_2, and heading_3 blocks using case-insensitive trimmed text. The markdown is replacement body content, not a wrapper that renames the toggle, and the server converts it into native Notion blocks, not flat/plain text. The server automatically handles Notion API limits: batches more than 100 child blocks, splits rich text over 2000 characters, and writes deeply nested blocks in additional passes, so callers can send a full multi-section toggle tree in one call with no need to pre-chunk or pre-split. If the markdown parses as one matching top-level toggle or toggleable heading wrapper, that wrapper is ignored and only its children are used as the replacement body. For supported markdown syntax, read resource easy-notion://docs/markdown. Page mentions: @Title. Returns: { success: true, block_id, type, deleted, appended }, where deleted and appended are counts, plus deleted_blocks for the deleted top-level body blocks when present and block_map for the top-level appended body blocks when present. A dry run instead returns { success: true, dry_run: true, operation, page_id, title, block_id, type, deleted, appended, would_delete_block_ids, append_parent_id }.

Inputs: title (required), page_id (required), markdown (required), dry_run, +2 more.

update_viewA

Update a Notion database view. Pass at least one update field. Null filter, sorts, or quick_filters values are forwarded to clear those fields.

Inputs: view_id (required), name, sorts, filter, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 43 tools

    Disambiguation4/5

    Most tools are clearly distinct by resource (page, block, toggle, database, view, comment, user). Some potential confusion exists between update_section/update_toggle/update_block and read_section/read_block/read_toggle, but descriptions clarify the target granularity. The pair add_database_entry/add_database_entries is intentionally similar but the plural is self-explanatory.

    Naming Consistency4/5

    The set predominantly uses verb_noun naming (create_page, read_page, update_page, archive_page, restore_page, query_database, add_database_entry, delete_database_entry). Minor deviations exist: get_view vs list_views, get_database vs list_databases, and get_me/get_config don't follow the verb_noun pattern, but the overall convention is consistent and predictable.

    Tool Count3/5

    43 tools is on the heavy side for a single MCP server, but the breadth roughly matches Notion's feature surface (pages, blocks, toggles, databases, views, comments, users). The count is justified by the domain, though it approaches the upper bound where navigation becomes burdensome.

    Completeness5/5

    The tool surface covers the full lifecycle for pages (create, read, update, archive, restore, duplicate, move), blocks (read, update, delete, append, replace), toggles (read, update, archive, restore), databases (create, get, list, query, update schema, add/update/delete entries), views (list, create, update, delete), comments, and users. Notable gaps like subpage deep-duplication and database inline toggling are explicitly documented as limitations rather than missing coverage.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables LLMs to interact with Notion workspaces via the Notion API, supporting page creation, database management, and content retrieval. It features markdown conversion to optimize token usage and enhanced error handling for more reliable workspace interactions.
      19
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A lightweight Notion MCP server that minimizes token usage by returning Markdown instead of raw JSON, enabling efficient read/write operations on Notion pages.
      9
      MIT