Easy Notion MCP

npx easy-notion-mcp

Contenido: Comparación · Configuración · Perfiles CLI · Configuración · Por qué markdown · Cómo funciona · Herramientas · Recursos MCP · Tipos de bloques · Ida y vuelta · Bases de datos · Recetario · Seguridad · Estabilidad · FAQ · Comunidad

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

¿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 crudo de bloques de Notion lleva metadatos por bloque (IDs de bloque, marcas de tiempo, objetos de autor) que un agente que lee contenido nunca necesita. Típicamente ~5–7×, con un rango de ~3× en páginas con mucho código a ~15× en páginas ricas, con ≥94% del contenido de la página preservado. Medido contra el servidor oficial de JSON crudo; 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 información igual, los dos formatos cuestan aproximadamente lo mismo (la proporción común de representación intermedia es ~1.0–1.06× en formas de página completamente representadas, y 1.32× en prosa típica), así que el ahorro es el metadato por bloque (UUIDs de bloque, marcas de tiempo, objetos de autor, envoltorios de anotaciones) que el JSON crudo lleva y una lectura de contenido nunca usa. Las consultas de bases de datos muestran una ventaja similar de ~7× con completitud de contenido total.

Metodología, resultados por clase y cada advertencia: .meta/research/token-bench-results-2026-06-13.md (re-ejecutable vía scripts/bench/lib/recompute-tiers.ts).

¿Cómo configuro easy-notion-mcp?

Con token de API

Crea una integración de Notion, copia el token, 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 tu configuración a nivel de usuario de Claude Code (-s user) y pasa NOTION_TOKEN directamente al proceso hijo MCP vía -e. Tu entorno de shell y tus rcfiles no se tocan — el token vive en el archivo de configuración de Claude Code, con alcance 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 del shell padre antes de iniciar OpenClaw:

export NOTION_TOKEN=ntn_your_integration_token

Esta forma export es el respaldo genérico para cualquier cliente MCP que herede el entorno del shell padre. Advertencia: solo persiste para 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 de arriba cuando uses Claude Code específicamente.

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

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

Ubicaciones de 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 CLI para acceso a Notion de bajo contexto

Usa el CLI easy-notion cuando un agente necesite acceso a Notion sin cargar toda la superficie de herramientas MCP, o cuando quieras integraciones de Notion separadas para diferentes modos de permisos. Los perfiles viven en ~/.config/easy-notion-mcp/profiles.json por defecto y referencian nombres de variables de entorno, no tokens crudos.

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 CLI destructivos soportan --dry-run como verificación previa de solo lectura. Ejecuta la misma búsqueda y validación de markdown donde sea posible, devuelve campos planificados tales como would_delete_block_ids, would_update, would_archive, o would_restore, y no muta Notion.

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

Con OAuth

Token de API + stdio es el predeterminado de menor fricción. Si estás ejecutando un despliegue compartido o quieres acceso por usuario, OAuth maneja la autenticación sin token para copiar y pegar.

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. Ver Configuración de OAuth abajo.

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, ingresa http://localhost:3333/mcp.

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

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

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 los encabezados de solicitud:

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

¿Por qué no localhost? Estas plataformas típicamente se ejecutan en Docker. localhost dentro de un contenedor se refiere al contenedor mismo, no a tu máquina anfitriona. host.docker.internal cierra la brecha.

Host HTTP y bearer: El servidor HTTP se vincula a 127.0.0.1 por defecto y el modo de token estático requiere NOTION_MCP_BEARER. host.docker.internal alcanza la IP de puente del anfitrión, así que establece NOTION_MCP_BIND_HOST=0.0.0.0 en el anfitrión y envía el encabezado 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 vía 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 discusiones de configuración y diseño. Los errores van a GitHub issues.

Configuración

Modo Stdio (token de API)

Acerca de los archivos .env (solo contribuidores): easy-notion-mcp carga un archivo .env desde el directorio de trabajo actual vía dotenv. En la práctica, esto significa que .env solo "funciona" cuando ejecutas el servidor desde un checkout clonado del repositorio (node dist/index.js después de npm install && npm run build), porque la raíz del repositorio es tu cwd. No se carga cuando el paquete se invoca vía npx easy-notion-mcp o una instalación global desde un directorio arbitrario — eso es comportamiento estándar del CLI de npm. Para la ruta npx, pasa NOTION_TOKEN vía la bandera -e en la configuración de Claude Code de arriba, o vía 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.

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

En 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 por defecto.

Postura de seguridad del modo HTTP

El transporte HTTP está diseñado para redes de confianza: autoalojamiento de operador único con un secreto bearer, u OAuth para despliegues compartidos. No está endurecido para exposición directa a internet abierta; 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 establecido se negará a iniciar. Establece un bearer de secreto compartido en el entorno del servidor, luego configura tu cliente MCP para enviarlo 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 faltantes o incorrectos reciben 401 { "error": "invalid_token" }. Rota el secreto reiniciando el servidor con un nuevo valor.

El enlace predeterminado es loopback. El servidor se vincula a 127.0.0.1 por defecto — 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 requerido independientemente del enlace. Bearer-always es el límite de confianza. La protección contra DNS-rebinding no está activada en el endpoint /mcp, y 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 maneje TLS y verificaciones de origen.

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

Las subidas de file:// son solo stdio. El markdown pasado a create_page, append_content, replace_content, update_section, o update_page.cover con URLs file:// es rechazado sobre 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 soportan solo un puñado de tipos de bloque, descartando silenciosamente callouts, toggles, tablas, ecuaciones y más.

easy-notion-mcp usa markdown GFM estándar que los agentes ya conocen. No hay nada nuevo que aprender, sin sintaxis de etiquetas personalizadas, sin objetos de bloque que construir. El agente escribe markdown, easy-notion-mcp maneja 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 soportados se preservan para los tipos de bloque que este servidor representa, y las omisiones y degradaciones conocidas están documentadas abajo. 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 { select: { name: "Done" } } anidados. 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. Toggles anidados dentro de toggles, columnas con tipos de contenido mixtos (listas + bloques de código + blockquotes), anidamiento profundo de listas, y unicode completo (japonés, chino, árabe, emoji) están cubiertos por pruebas de ida y vuelta. La búsqueda de encabezados update_section no distingue mayúsculas y devuelve los encabezados disponibles en caso de fallo. add_database_entries maneja fallos parciales, y las entradas exitosas y fallidas se devuelven por separado para que los agentes puedan reintentar solo los fallos.

¿Qué herramientas proporciona easy-notion-mcp?

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

Páginas (20 herramientas)

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

restore_toggle está intencionalmente basado en ID: pasa el ID de bloque archivado devuelto por archive_toggle. Notion no expone la enumeración de hijos archivados para 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)

Cada fila de list_pages devuelve id, title, created_time y last_edited_time, para que un agente pueda distinguir páginas activas de 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 ediciones de contenido y propiedades de la página. Nota 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)

Las herramientas de escritura de bases de datos rechazan nombres de propiedades desconocidos y tipos de propiedades no soportados con un error claro en lugar de descartarlos silenciosamente. Llama a get_database primero para confirmar nombres y tipos de propiedades. Tipos de propiedades soportados para escrituras: title, rich_text, number, select, multi_select, date, checkbox, url, email, phone, status, relation, people. Para people, pasa una sola cadena de ID de usuario o un array de IDs de usuario. Los tipos calculados (formula, rollup, unique_id, created_time, last_edited_time, created_by, last_edited_by) son poblados por Notion y no pueden establecerse vía API. Las escrituras de valor también son rechazadas para files, verification, place, location y button. Para escrituras de relaciones, pasa una sola cadena de ID de página ("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, mapea valores al formato de propiedades de Notion y maneja 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 API redundantes durante operaciones por lotes.

Vistas (6 herramientas)

Comentarios (2 herramientas)

Usuarios (2 herramientas)

Servidor (1 herramienta)

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

¿Qué recursos MCP están disponibles?

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

¿Qué tipos de bloque soporta easy-notion-mcp?

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

Markdown estándar

Sintaxis específica de Notion

Saltos de línea y collapse_soft_wraps

Por defecto, una sola nueva línea dentro de un párrafo se escribe tal cual. El Markdown con ajuste duro en 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.

Cada herramienta de escritura de Markdown acepta un collapse_soft_wraps: true opcional, que aplica la semántica de ajuste suave de CommonMark en su lugar: una sola nueva línea dentro de un párrafo se convierte en un espacio, por lo que un archivo con ajuste duro llega como párrafos fluidos. Las líneas en blanco aún separan bloques y los bloques de código delimitados no se modifican en ambos 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 leíste desde Notion, o los saltos de línea intencionales se perderán.

Los saltos duros explícitos (una barra invertida al final o dos espacios al final) se comportan de manera idéntica con o sin la opción, pero difieren según la ruta de escritura:

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

Título y duplicación 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 en la página dos veces. Se aplica solo cuando el primer bloque convertido de nivel superior es un heading_1 simple (no alternable), y el valor predeterminado es falso.

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 es necesario; el valor predeterminado sigue siendo verdadero y no ha cambiado.

¿Puedo leer y reescribir páginas con el formato preservado?

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 reportan con advertencias explícitas.

read_page devuelve las convenciones de Markdown que create_page acepta: encabezados, listas, tablas, llamadas, alternadores, 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 lista los IDs y tipos de bloques omitidos. Escribir ese Markdown de vuelta a través de 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, usa @[Title](notion-url), que es una construcción separada del tipo de bloque link_to_page.

Las notas de reuniones de Notion AI (y los bloques transcription obsoletos) se renderizan como un alternador 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 de renderizado 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 reportan con una advertencia. En la ruta replace_content, los marcadores e incrustaciones se escriben como URLs desnudas (estos sí advierten), mientras que los bloques file, audio y video se reducen a sus URLs silenciosamente. Las anotaciones de subrayado y color de texto 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 vuelta preservando el formato, la estructura y el contenido compatibles. 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 proporciona tres estrategias de edición para diferentes casos de uso:

• replace_content — Reemplaza todo el contenido de una página con nuevo Markdown. Mejor para reescrituras completas.
• update_section — Reemplaza una sola sección identificada por nombre de encabezado. Por defecto, el Markdown de reemplazo incluye el encabezado y reemplaza la sección completa. Pasa preserve_heading: true (o CLI --preserve-heading) para mantener el ID del bloque de encabezado existente, texto, tipo, comentarios y estado alternable mientras reemplaza destructivamente solo el cuerpo de la sección.
• find_replace — Encuentra y reemplaza texto específico en cualquier parte de la página, preservando todo el otro contenido y archivos adjuntos. Mejor para ediciones quirúrgicas.

Pasa dry_run: true en las herramientas MCP, o --dry-run en la CLI, antes de ediciones destructivas cuando quieras una respuesta 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 al formato de propiedades de Notion automáticamente.

easy-notion-mcp admite crear y actualizar bases de datos con esquemas tipados, consultar con filtros y ordenamientos, y operaciones masivas a través de 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 con cero segunda instalación. Son gratuitas y soberanas: tu propio agente, tu propio token, configuración de token API sin OAuth y consultas de bases de datos en plan gratuito.

Estos pasos funcionan a través de las herramientas MCP o el conector de 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 bloque fuente con search_in_page y un filtro de deduplicación estructurado, y la superficie CLI actual no expone ese flujo de trabajo 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 Item Key para cada elemento candidato, add_database_entry o add_database_entries para nuevas filas, y una verificación final query_database.

El resultado en vivo probado fue 5 filas de una reunión de planificación. Los propietarios y fechas de vencimiento faltantes se almacenaron en el multi-select Flags, no en Source, y un filtro 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 conteo en 5 con cero duplicados. Una búsqueda de texto libre para el nombre compartido de la reunión devolvió cada fila porque también escaneó Source, por lo que esta receta usa el filtro exacto de Clave de Elemento para deduplicar.

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-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-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 filas que necesitan correcciones, luego re-consultar. Para texto de página, la secuencia es find_replace con dry_run: true, find_replace con replace_all: true, luego read_page para verificar.

La reparación de base de datos en vivo probada normalizó 4 filas con valores mixtos Eng y engineering a una opción consistente mientras dejaba filas no relacionadas sin cambios. La edición de página en vivo probada reemplazó 4 ocurrencias en párrafos y un cuerpo de encabezado. Advertencia: la coincidencia de opciones select y status no distingue entre mayúsculas y minúsculas, y las escrituras se ajustan a la capitalización de la opción existente más temprana. 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, renombra 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 despliegues de 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 crudos 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 el cliente. Establece NOTION_TRUST_CONTENT=true para deshabilitar el aviso de Markdown si controlas el espacio de trabajo.

Saneamiento de URLs: javascript:, data: y otros protocolos de URL inseguros se eliminan y se renderizan 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 y es solo aditivo: nombres de herramientas, esquemas de entrada de herramientas, formas de retorno de herramientas, las convenciones personalizadas de Markdown y el vocabulario de códigos de advertencia no cambiarán de manera que rompa compatibilidad hasta un futuro lanzamiento 2.0. Los cambios aditivos (nuevas herramientas, nuevos parámetros opcionales, nuevos campos de respuesta opcionales, nuevos códigos de advertencia) no rompen compatibilidad y pueden enviarse en lanzamientos 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. Consulta el CHANGELOG para la declaración completa del contrato y el historial por lanzamiento.

Preguntas frecuentes

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

El paquete npm MCP oficial de Notion (@notionhq/notion-mcp-server) es un proxy de API crudo 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 usa un formato de Markdown personalizado basado en etiquetas HTML, mientras que easy-notion-mcp usa sintaxis de Markdown estándar.

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

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

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

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

¿easy-notion-mcp maneja 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, incluyendo japonés, chino, ruso, árabe y emojis, están cubiertos por pruebas de ida y vuelta para estas formas compatibles.

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

Sí. add_database_entries devuelve matrices separadas de 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 concretas de funciones, los issues de GitHub siguen siendo el canal canónico.

Contribuciones

Se aceptan issues y PRs en GitHub.

Licencia

MIT