/setup-notion.es

description: "Lesson command"
duration: "~10 min"
prerequisites: ["Tener cuenta de Notion (plan gratuito OK)", "Navegador disponible", "Node.js 18+"]
level: "beginner"
tags: ["setup", "notion", "ncli", "mcp", "oauth"]
nonInteractiveMode: incompatible

Configuración de Notion CLI (ncli) + Hosted MCP (solo OAuth)

Step 0: Verificar el progreso de configuración

**Lo que la IA ejecuta automáticamente:** 1. Ejecutar `uv run python tools/setup_progress.py show --current setup-notion` para mostrar el progreso 2. Detectar automáticamente la configuración existente:

• `which ncli` para verificar si ncli está instalado
• Para Claude Code: verificar si el servidor `notion` está definido en `~/.claude/mcp_settings.json`
• Para Cursor: verificar si el servidor `notion` está definido en `~/.cursor/mcp.json`
• Si ncli está instalado y MCP está configurado, puede ejecutar solo el Step 6 (prueba de conexión) y marcarlo como completado

Lo que hará en esta sesión

| Elemento | Contenido | |----------|-----------| | Objetivo | Conectar ncli (Notion CLI) y el Hosted MCP oficial de Notion mediante **OAuth**, para operar Notion desde el terminal y desde herramientas compatibles con MCP | | Duración | ~10 minutos | | Requisitos previos | Cuenta de Notion (plan gratuito OK), Node.js 18+, navegador | | Nivel de operación | No se necesitan comandos CLI (todo lo ejecuta automáticamente la IA + una sola aprobación OAuth en el navegador) | | Método de autenticación | **Esta configuración usa solo OAuth** (no se requieren claves API).<br>Nota: algunos scripts heredados (p. ej. `tools/run_lesson_14_11.py`) todavía requieren `NOTION_API_KEY`. Consulta `.env.example` para más detalles. |

**Flujo de la sesión:** 1. Instalar ncli (@sakasegawa/ncli) (la IA lo ejecuta automáticamente) 2. Ejecutar `ncli login` y aprobar el OAuth de Notion en el navegador 3. Verificar con `ncli whoami` / `ncli search` 4. Añadir el Notion Hosted MCP (OAuth) al archivo de configuración MCP (la IA lo escribe automáticamente) 5. Reiniciar Claude Code / Cursor y aprobar el diálogo OAuth en el primer uso 6. Prueba de conexión MCP

> **¿Por qué Hosted MCP + OAuth?** El flujo antiguo de Internal Integration Token obligaba a crear una integración en Notion y a compartir cada página individualmente con "Add connections". Con OAuth, un único inicio de sesión en el navegador concede acceso a todo el workspace, por lo que **en este flujo Hosted MCP** compartir página por página **no es necesario**. Si todavía necesitas ejecutar scripts heredados que leen `NOTION_API_KEY` directamente (p. ej. `tools/run_lesson_14_11.py`), sigue usando un Internal Integration Token junto con esta configuración OAuth.

> **Consejo**: Si la respuesta de la IA se detiene a mitad de camino, escriba "por favor continúe" o "se detuvo" para reanudar.

---

Verificación de preparación

**Configuración de AskQuestion:**

{
  "title": "Confirmación antes de la sesión",
  "questions": [{
    "id": "readiness",
    "prompt": "¿Está preparado/a?",
    "options": [
      {"id": "ready", "label": "¡Preparado/a! Comencemos"},
      {"id": "check_prereq", "label": "Quiero verificar los requisitos previos"},
      {"id": "which_tool", "label": "Quiero confirmar si uso Claude Code o Cursor"},
      {"id": "different_lesson", "label": "Quiero ir a otra lección"}
    ]
  }]
}

(ready -> Ir al Step 1) (check_prereq -> Indicar: "Está listo/a si tiene una cuenta de Notion (plan gratuito OK), puede iniciar sesión por navegador y tiene Node.js 18 o superior instalado.") (which_tool -> Explicar: "La ubicación del archivo de configuración MCP difiere entre Claude Code y Cursor. El Step 4 le guiará con los pasos para cada uno.") (different_lesson -> Mostrar la lista de módulos)

---

Step 1: Instalar ncli (Notion CLI)

**Lo que hace la IA:** 1. Verificar la versión de Node.js: `node --version` (se requiere 18 o superior) 2. Verificar si ncli ya está instalado: `which ncli` 3. Si no está instalado, ejecutar el siguiente comando:

npm install -g @sakasegawa/ncli

4. Después de la instalación, verificar con `ncli --version`

**Configuración de AskQuestion:**

{
  "title": "Step 1: Instalar ncli",
  "questions": [{
    "id": "ncli_status",
    "prompt": "Se ejecutó la instalación de ncli. Verifique el resultado.",
    "options": [
      {"id": "installed", "label": "Se instaló correctamente"},
      {"id": "npm_error", "label": "Hubo un error con npm install"},
      {"id": "no_node", "label": "Node.js no está instalado"},
      {"id": "command_not_found", "label": "No se encuentra el comando ncli"}
    ]
  }]
}

(installed -> Ir al Step 2) (npm_error -> Ejecutar `npm cache clean --force` y reintentar. Si hay error de permisos, indicar `sudo npm install -g @sakasegawa/ncli`) (no_node -> Indicar: "Instale la versión LTS (18 o superior) desde https://nodejs.org/") (command_not_found -> Verificar la instalación con `npm list -g @sakasegawa/ncli`. Si es un problema de PATH, verificar con `npm bin -g` e indicar cómo agregar al PATH)

---

Step 2: Iniciar sesión en Notion mediante OAuth con ncli

**Lo que hace la IA:** 1. Ejecutar en el terminal:

ncli login

2. ncli abre automáticamente la pantalla OAuth de Notion en el navegador 3. El usuario sigue el flujo en pantalla:

• Iniciar sesión en Notion (si no lo está)
• Seleccionar el workspace al que conceder acceso
• Hacer clic en "Allow access"

4. Si tiene éxito, el terminal muestra "Logged in as ..."

**Mensaje para mostrar al usuario:**

Se abrió la pantalla OAuth de Notion en el navegador.

1. Si no ha iniciado sesión en Notion, inicie sesión
2. Seleccione el workspace al que desea conceder acceso
3. Haga clic en "Allow access" para aprobar

Tras la aprobación, la pestaña del navegador se cierra automáticamente y el terminal mostrará un mensaje de inicio de sesión exitoso.

No es necesario introducir ninguna clave API (secret_xxx). Todo se completa con el fluj