Notion MCP — Casos de uso, Instalar & Demo en vivo

Por qué usarlo

Características clave

Oficial — publicado por Notion, sigue su API fielmente
Consultas de bases de datos con filtro/ordenamiento — trata Notion como un almacén estructurado
Escrituras a nivel de bloque — añade, actualiza, archiva bloques específicos, no páginas completas
Búsqueda de páginas en todo el espacio de trabajo (lo que compartiste con la integración)

Demo en vivo

Cómo se ve en la práctica

notion.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ]
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ]
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ]
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ]
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "notion",
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "notion": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@notionhq/notion-mcp-server"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add notion -- npx -y @notionhq/notion-mcp-server

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: Notion

Que un agente revise tu PRD en busca de vacíos

👤 Gestores de producto, líderes técnicos ⏱ ~15 min intermediate

Cuándo usarlo: Redactaste una especificación y quieres una lectura crítica antes de compartirla con ingeniería.

Requisitos previos

Token de integración interna de Notion — notion.so/my-integrations → Nueva integración → copia el secreto
Página compartida con la integración — En la página: ••• → Conexiones → añade tu integración

Flujo

Obtén el contenido de la página

Lee la página de Notion en <URL>. Resume en 5 puntos lo que propone esta especificación.✓ Copiado

→ Resumen preciso de 1 párrafo — prueba que el agente lo entendió
Encuentra áreas mal especificadas

Enumera cada lugar donde la especificación es vaga: casos de error faltantes, comportamiento de borde indefinido, propiedad poco clara, sin plan de despliegue, sin métrica de éxito.✓ Copiado

→ Lista numerada de vacíos con referencias de página
Redacta preguntas para la revisión

Convierte esos vacíos en 5-10 preguntas específicas que un ingeniero revisor haría. Añádelas a la página de Notion como una nueva sección 'Preguntas Abiertas'.✓ Copiado

→ Bloque de preguntas añadido a la página

Resultado: Una especificación más ajustada más una sección de Preguntas Abiertas que inicia las conversaciones correctas antes de la reunión de revisión.

Errores comunes

El agente alucina detalles que no están en la especificación — En el prompt, insiste: 'solo señala vacíos; no inventes hechos; cita la sección donde ocurre cada vacío'
Las especificaciones largas se truncan al obtenerlas — Usa retrieve_block_children página por página si la página tiene muchos bloques; no confíes en una única llamada get_page

Combinar con: linear

Auto-genera una página de standup diario desde Linear + GitHub

👤 Gestores de ingeniería, scrum masters ⏱ ~10 min intermediate

Cuándo usarlo: Ejecutas una página de standup diario en Notion y quieres que se complete previamente con la actividad de ayer.

Requisitos previos

Una base de datos 'Standups' en Notion — Tiene propiedades: Fecha (date), Equipo (select), Estado (rich_text)

Flujo

Recopila la actividad de ayer

De Linear, enumera los problemas movidos a Hecho en las últimas 24h para el equipo ENG. De GitHub, enumera los PR fusionados por nuestro equipo.✓ Copiado

→ Lista de actividad combinada
Construye el contenido del standup

Formatea como: Logros (entregado), En vuelo (PR abiertos), Bloqueadores (problemas etiquetados 'blocked'), Enfoque de hoy (problemas en progreso). Mantén cada sección bajo 5 puntos.✓ Copiado

→ Lista de bloques formateada
Crea la página de Notion

Crea una nueva página en la base de datos Standups. Fecha = hoy, Equipo = ENG, y pega el contenido como bloques estructurados (h2 por sección).✓ Copiado

→ URL de página devuelta

Resultado: Una página de standup completada previamente lista para la sincronización de las 9am, ahorra 15 minutos de ajetreo.

Errores comunes

Los nombres de propiedades de la base de datos distinguen mayúsculas de minúsculas y deben coincidir exactamente — Enumera las propiedades con retrieve_database antes de la primera ejecución y codifica exactamente las claves

Combinar con: linear · github

Construye un bot de preguntas y respuestas listo para Slack sobre tus documentos de Notion

👤 Líderes de operaciones, gestores de soporte ⏱ ~20 min intermediate

Cuándo usarlo: Los nuevos empleados siguen haciendo las mismas preguntas. Tus respuestas ya están escritas en Notion — solo que no se pueden encontrar.

Requisitos previos

Los documentos de incorporación se encuentran en un espacio conocido de Notion — Comparte la página principal con la integración para que todos los hijos hereden el acceso

Flujo

Busca en el espacio de trabajo

Busca en Notion páginas que coincidan con: '[pregunta del usuario]'. Devuelve los 5 títulos de página principales y URLs.✓ Copiado

→ Lista de resultados clasificada
Lee la más relevante

Para los 2 principales, obtén el contenido completo. Cita los pasajes que responden la pregunta.✓ Copiado

→ Citas textuales + URLs de origen
Responde con citas

Responde la pregunta del usuario en 2-3 oraciones, fundamentada solo en esas citas. Termina con: 'Fuente: <url>'. Si los documentos no responden realmente, dilo.✓ Copiado

→ Respuesta con cita u honesto 'no está en los documentos'

Resultado: Respuestas fundamentadas que permiten a las personas encontrar su propio camino hacia el documento de origen — sin más 'dónde está X?' en Slack.

Errores comunes

El agente fabrica una respuesta plausible cuando los documentos no la cubren realmente — Instrucción explícita: 'si las citas recuperadas no responden la pregunta, responde con No veo esto en nuestros documentos — sin conjeturas'
La búsqueda de Notion se basa en palabras clave, pierde coincidencias semánticas — Si los resultados se sienten delgados, empáralos con una pila RAG adecuada (incrustra contenido de Notion en una BD vectorial)

Convierte notas de reunión en problemas de Linear

👤 Líderes técnicos, gestores de producto ⏱ ~10 min beginner

Cuándo usarlo: Tomaste notas aproximadas durante una reunión en Notion. Ahora necesitas extraer los elementos de acción.

Requisitos previos

MCP de Linear instalado — Ver guía de linear

Flujo

Lee la página de la reunión

Lee la página de Notion en <URL>. Extrae cada elemento de acción — cualquier cosa expresada como 'X hará Y' o 'debemos Z'.✓ Copiado

→ Lista con propietario si se menciona
Confirma antes de crear

Muéstrame la lista de acciones. Para cada uno, propone un título de Linear, equipo y prioridad. No crees aún.✓ Copiado

→ Tabla de ejecución en seco para revisión humana
Crea elementos aprobados

Crea problemas de Linear para los elementos 1, 3 y 5. Vincula cada uno de vuelta a la página de reunión de Notion.✓ Copiado

→ URLs de problemas de Linear devueltas

Resultado: Acciones de reunión que realmente se rastrean en lugar de perderse en una página de Notion que nadie revisita.

Errores comunes

El agente trata cada punto informativo como una acción — En el prompt: 'solo elementos con un propietario claro O un entregable — descarta todo lo demás'

Combinar con: linear

Audita tus documentos de Notion por antigüedad

👤 Líderes de documentación, ingenieros de DevEx ⏱ ~20 min intermediate

Cuándo usarlo: Limpieza trimestral — encuentra documentos que no se han tocado en 6+ meses y probablemente mienten.

Requisitos previos

Una página raíz para el área de documentación — p.ej., /Ingeniería/Documentos — compartido con la integración

Flujo

Enumera páginas secundarias con marcas de tiempo

Enumera todas las páginas descendientes bajo la página 'Documentación de Ingeniería'. Para cada una: título, URL, hora_de_última_edición, última_edición_por.✓ Copiado

→ Inventario completo
Filtra a páginas antiguas

Filtra a páginas editadas por última vez hace más de 180 días. Agrupa por sección de nivel superior.✓ Copiado

→ Lista antigua por sección
Etiqueta para revisión

Para cada página antigua, añade un bloque de acción en la parte superior: '⚠ Necesita revisión — última actualización <fecha>. Ping <última-edición> para confirmar.'✓ Copiado

→ Páginas actualizadas con pancarta de revisión

Resultado: Un área de documentación donde la antigüedad es visible, no oculta — y los propietarios reciben un empujón para actualizar o eliminar.

Errores comunes

Algunas páginas son deliberadamente archivales (ADRs, postmortems) y NO deben obtener la pancarta — Filtra por etiqueta o padre — excluye cualquier cosa bajo /Archivo o etiquetada 'histórica'

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

notion + linear

Construye un proyecto de Linear a partir de una PRD de Notion

Lee la PRD de Notion en <URL>, extrae entregables, y crea un proyecto de Linear coincidente con problemas agrupados por hito.✓ Copiado

notion + github

Mantén un README sincronizado con un documento de diseño de Notion

Lee la página de Notion '<Diseño de API>' y actualiza el README.md en nuestro repositorio api para que coincida — abre un PR con el diff.✓ Copiado

notion + sentry

Publica informes de calidad de ingeniería semanales en una base de datos de Notion

Extrae las estadísticas de errores de Sentry de esta semana por proyecto y crea una nueva página en la base de datos 'Calidad Semanal' de Notion.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
search	query, filter?: {property, value}	Descubrimiento — encuentra páginas por palabra clave en todo el espacio de trabajo	1 API call
retrieve_page	page_id	Obtén metadatos/propiedades de página — no bloques de contenido	1 API call
retrieve_block_children	block_id, start_cursor?	Lee contenido real de la página — llama repetidamente hasta que no haya next_cursor	1 API call (may need pagination)
append_block_children	block_id, children: Block[]	Añade contenido a una página o bajo un bloque específico	1 API call
update_block	block_id, {type}: {...}	Edita texto/contenido de un bloque existente en su lugar	1 API call
create_page	parent: {database_id}\|{page_id}, properties, children?	Crea una nueva página — bajo una página padre o dentro de una base de datos	1 API call
query_database	database_id, filter?, sorts?	Consulta estructurada — filtra/ordena entradas en una base de datos	1 API call
update_page	page_id, properties	Actualiza propiedades a nivel de página (estado, etiquetas, fecha)	1 API call
retrieve_database	database_id	Introspecciona nombres/tipos de propiedades antes de escribir	1 API call

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Notion: promedio 3 req/seg por integración, se permiten picos. 429 agresivamente a escala.
Tokens por llamada: 500–3000 tokens por página dependiendo del conteo de bloques
Monetario: Gratis — API incluida en cualquier plan de Notion
Consejo: Las páginas con muchos bloques anidados son caras de leer completamente. Busca primero, obtén solo páginas objetivo.

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: read_content

Almacenamiento de credenciales: Secreto de integración interna en variable de entorno NOTION_API_KEY

Salida de datos: Todas las llamadas a api.notion.com

No conceder nunca: update_content insert_content

Resolución de problemas

Errores comunes y soluciones

object_not_found

La página existe pero no se comparte con tu integración. Abre la página → ••• → Conexiones → añade integración.

validation_error on create_page

Los nombres/tipos de propiedades en tu carga no coinciden con el esquema de la base de datos. Llama a retrieve_database primero y copia las claves exactas.

429 rate limited

Notion limita a ~3 req/seg. Añade un sleep de 350ms entre escrituras o agrupa mediante append_block_children (envía 100 bloques por llamada, no 100 llamadas).

Page content looks empty

retrieve_page devuelve solo metadatos — el contenido está en bloques. Llama a retrieve_block_children para obtener texto real.

Alternativas

Notion vs otros

Alternativa	Cuándo usarla	Contrapartida
Confluence MCP	Tu organización está en Confluence/Atlassian en lugar de Notion	Modelo de permisos más pesado; los flujos de trabajo del agente tienden a ser más lentos
Obsidian / filesystem MCP	Tu base de conocimiento son archivos markdown locales	Sin sincronización o permisos multiusuario, pero sin costo de API e lecturas instantáneas

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills