repo_Claude/.claude/skills/init-jupyter/SKILL.md

name, description, argument-hint, disable-model-invocation, user-invocable, allowed-tools

name	description	argument-hint	disable-model-invocation	user-invocable	allowed-tools
init-jupyter	Inicializa o inicia Jupyter Lab via MCP con kernel compartido. Detecta notebooks existentes automáticamente.	ruta-proyecto	true	true	Bash, Read, Write, Edit, Glob

Inicializar/Iniciar Proyecto Jupyter via MCP

Este skill gestiona entornos Jupyter Lab integrados con Claude via MCP. Detecta automáticamente si ya existe un proyecto configurado.

Modo de Colaboración (Kernel Compartido)

IMPORTANTE: Para que las ejecuciones de Claude sean visibles en Jupyter Lab, se debe usar el mismo kernel que el notebook abierto. Esto permite:

• Ver las ejecuciones de Claude en tiempo real en Jupyter Lab
• Compartir variables y estado entre Claude y el usuario
• Colaboración real entre ambos en el mismo notebook

Flujo de decisión

1. Detectar notebooks existentes

Buscar archivos .ipynb en:

• Raíz del proyecto
• Carpeta notebooks/
• Cualquier subcarpeta

find [ruta] -name "*.ipynb" -type f 2>/dev/null | head -5

2. Si HAY notebooks existentes → Iniciar directamente

2a. Verificar que MCP está configurado con kernel compartido

• Comprobar si existe .claude/settings.local.json con configuración de jupyter
• Verificar que incluye --start-new-runtime false para colaboración
• Si no existe o falta la configuración, crearlo (ver paso 3f)

2b. Verificar que jupyter-mcp-server está instalado

which jupyter-mcp-server || uv tool install jupyter-mcp-server

2c. Iniciar Jupyter via MCP

source .venv/bin/activate 2>/dev/null || true
jupyter lab --no-browser --NotebookApp.token='' --NotebookApp.password='' --NotebookApp.disable_check_xsrf=True

2d. Informar al usuario que Jupyter está corriendo y puede usar las herramientas MCP de Jupyter desde Claude.

3. Si NO hay notebooks → Inicializar proyecto completo

Seguir estos pasos:

3a. Validar ubicación

• Si se proporciona $1, usar esa ruta
• Si no, usar el directorio actual

3b. Inicializar proyecto con uv (si no existe pyproject.toml)

cd [ruta] && uv init

3c. Crear entorno virtual

uv venv

3d. Instalar dependencias

uv add jupyter jupyter-collaboration

3e. Instalar jupyter-mcp-server

uv tool install jupyter-mcp-server

3f. Configurar MCP para Claude (con kernel compartido) Crear o actualizar .claude/settings.local.json:

{
  "mcpServers": {
    "jupyter": {
      "command": "jupyter-mcp-server",
      "args": [
        "--jupyter-url", "http://localhost:8888",
        "--start-new-runtime", "false"
      ]
    }
  }
}

Parámetros clave:

• --jupyter-url: URL del servidor Jupyter (por defecto localhost:8888)
• --start-new-runtime false: CRÍTICO - Conecta al kernel existente en lugar de crear uno nuevo

3g. Crear carpeta notebooks (opcional)

mkdir -p notebooks

3h. Iniciar Jupyter via MCP

source .venv/bin/activate
jupyter lab --no-browser --NotebookApp.token='' --NotebookApp.password='' --NotebookApp.disable_check_xsrf=True

Ejemplos de uso

Iniciar/inicializar en directorio actual:

/init-jupyter

Iniciar/inicializar en ruta específica:

/init-jupyter ~/proyectos/mi-analisis

Flujo de trabajo colaborativo (Kernel Compartido)

Cómo funciona la colaboración

1. Usuario inicia Jupyter Lab (via este skill)
2. Usuario abre un notebook en Jupyter Lab → se inicia un kernel
3. Claude se conecta al MISMO kernel via MCP con --start-new-runtime false
4. Ambos comparten:
   • El mismo estado de variables
   • El mismo historial de ejecución
   • Las salidas son visibles para ambos en tiempo real

Pasos para colaborar

1. Ejecutar /init-jupyter para iniciar Jupyter Lab
2. Abrir el navegador en http://localhost:8888
3. Abrir o crear el notebook deseado
4. Claude ya puede ejecutar celdas y el usuario verá las ejecuciones en su Jupyter Lab

Obtener kernel ID específico (opcional)

Si hay múltiples kernels corriendo, puedes obtener el ID del kernel activo:

curl -s http://localhost:8888/api/kernels | jq '.[0].id'

Y configurar MCP con ese kernel específico:

{
  "mcpServers": {
    "jupyter": {
      "command": "jupyter-mcp-server",
      "args": [
        "--jupyter-url", "http://localhost:8888",
        "--runtime-id", "KERNEL_ID_AQUI"
      ]
    }
  }
}

Notas importantes

• Siempre usa MCP: Jupyter se ejecuta siempre de forma que Claude pueda interactuar via MCP
• Kernel compartido por defecto: Con --start-new-runtime false, Claude usa el kernel existente
• Si detecta notebooks existentes, NO reinicializa el proyecto, solo inicia Jupyter
• Si el proyecto ya tiene pyproject.toml, no ejecuta uv init
• La configuración MCP se guarda en .claude/settings.local.json del proyecto
• El servidor MCP permite a Claude crear, editar y ejecutar celdas de notebooks
• jupyter-collaboration ya está incluido en las dependencias para sincronización en tiempo real