Jupyter VS Code MCP

Extensión de VS Code que expone operaciones de Jupyter Notebook como herramientas MCP sobre HTTP puro — una URL portátil para cada agente de codificación de IA. Sin rutas absolutas, sin comando node, sin cableado de stdio.

Apunta cualquier cliente MCP a la URL, y el agente podrá explorar, editar, ejecutar y depurar notebooks en tu sesión activa del editor: ve las mismas celdas que ves, se comunica con el mismo kernel que usa tu notebook (local o remoto — Colab incluido), y cada acción se refleja en la interfaz real de VS Code.

Características

Edición de notebooks con identificadores de celda estables

• Cada celda se identifica mediante un único esquema uniforme: #NB-xxxxxxxx, persistido en el campo estándar cell id de nbformat 4.5. Sobrevive a ediciones, inserción/eliminación de otras celdas, cambios de índice, guardado/reapertura, recargas de la extensión — incluso al copiar el archivo a otra máquina.

• Los IDs nunca se reutilizan después de un borrado: las celdas nuevas siempre reciben IDs aleatorios nuevos. jupyter_get_summary asigna IDs a cualquier celda que carezca de uno (p. ej., creada a mano en la interfaz), de modo que cada identificador notificado se puede reutilizar de inmediato.

• Los índices son siempre de base 0 (resumen, fuentes, rangos de ejecución, salidas) — sin convenciones mixtas.

Control de ejecución no bloqueante

• jupyter_run_cells inicia la ejecución y regresa de inmediato; sondea con jupyter_wait_until_idle o toma una instantánea con jupyter_get_status. Sin esperas ciegas, sin timeouts de MCP en celdas largas.

• Protección de disponibilidad del kernel: ejecutar contra un kernel muerto o ausente devuelve pistas accionables en lugar de bloquearse.

• jupyter_interrupt_kernel aborta la ejecución actual conservando todas las variables.

Inteligencia de kernel (nivel Copilot)

• jupyter_get_variables — informes de variables con información de tipos: DataFrame/Series como {shape, columns[:8], head(2)}, ndarray como {shape, dtype}, contenedores con length, escalares como reprs cortos. Usa la API oficial de vista de variables de Jupyter cuando está disponible; de lo contrario, una sonda silenciosa del kernel que nunca toca el contador de ejecución. El filtrado opcional por símbolos de documento oculta el ruido interno solo cuando los símbolos están realmente disponibles.

• jupyter_get_pip_packages — inventario del entorno (nombre + versión) desde el entorno activo del kernel.

• jupyter_install_packages — pip se ejecuta dentro del intérprete del propio kernel, por lo que los paquetes se instalan en el runtime que el notebook usa realmente — incluidas máquinas virtuales remotas como Colab, nunca en el host local. Soporta especificaciones de versión y --upgrade, verifica que cada especificación se resuelva después e informa de fallos reales (con la cola real de la salida de pip) en lugar de fingir éxito.

• jupyter_get_status sondea el kernel en vivo para obtener la versión/plataforma real de Python en lugar de confiar en metadatos obsoletos.

• jupyter_select_kernel abre el selector de kernel nativo de VS Code cuando no hay ningún kernel activo.

Transporte MCP solo por red

• Streamable HTTP (especificación MCP 2025-11-25) con respuestas en JSON puro — un cliente mínimo funciona solo con curl.

• Endpoints: /mcp (además del heredado /sse), GET /health para comprobar disponibilidad y sondear la versión.

• Se admiten múltiples sesiones de agente concurrentes; las sesiones sobreviven a cambios en caliente del puerto.

Informes honestos

Los errores incluyen contexto y pistas para el siguiente paso: kernel ausente → guía de arranque, ID obsoleto → actualizar mediante el resumen, fallo en pip install → cola real del error de pip, kernel ocupado → nota explícita de aplazamiento en lugar de resultados vacíos en silencio.

Related MCP server: Jupyter MCP Server

Herramientas

IDs de celda estables

Cada celda recibe un ID persistente aleatorio (#NB-xxxxxxxx) escrito en el campo estándar cell id de nbformat 4.5 — el mismo hueco que la propia plataforma lee y conserva en guardado/carga. El ID es inmune a cambios de posición, ediciones de contenido, inserciones/eliminaciones de celdas adyacentes y ciclos de reapertura. Prefiere los IDs a los índices; llama a jupyter_get_summary para descubrirlos (también rellena los IDs que faltan en celdas creadas fuera de las herramientas).

La entrada de 8 dígitos hexadecimales sin prefijo (abcd1234) se acepta como abreviatura de #NB-abcd1234.

Agentes compatibles

Cualquier cliente MCP que hable HTTP funciona. Configuraciones comunes:

Claude Code, Cursor, Windsurf, Cline, Copilot:

{
  "mcpServers": {
    "jupyter-vscode-mcp": {
      "url": "http://localhost:9123/mcp"
    }
  }
}

OpenCode, Kilo Code:

{
  "mcp": {
    "jupyter-vscode-mcp": {
      "type": "remote",
      "url": "http://localhost:9123/mcp",
      "enabled": true
    }
  }
}

Ejecuta "Jupyter VS Code MCP: Show MCP Configuration" desde la paleta de comandos → elige tu agente → el fragmento se copia al portapapeles.

Instalación y ejecución

Descarga el .vsix más reciente desde Versiones, luego:

code --install-extension jupyter-vscode-mcp-<version>.vsix

1. Abre cualquier .ipynb — el servidor se inicia automáticamente en 127.0.0.1:9123 (la barra de estado muestra el estado; haz clic para alternar).

2. Añade la configuración de URL anterior a tu agente.

3. Comprueba la disponibilidad en cualquier momento: curl http://localhost:9123/health.

Configuración: jupyter-vscode-mcp.mcpPort (por defecto 9123, aplicado en caliente), jupyter-vscode-mcp.autoStart (por defecto true).

Flujo de trabajo recomendado

jupyter_list_open_notebooks   → pick notebook
jupyter_get_summary           → stable #NB-* IDs, exec state        (0-based)
jupyter_get_cell_source       → read only what you need
jupyter_edit_cell             → IDs stay valid after edits
jupyter_run_cells             → starts async, returns immediately
jupyter_wait_until_idle       → blocks until done (or poll get_status)
jupyter_get_outputs           → inline short text, artifact files for big/binary
jupyter_get_variables         → inspect kernel state after runs

Arquitectura

AI agent ──HTTP/JSON-RPC──▶ VS Code extension (in-process http server :9123)
                                 │ vscode.* APIs + ms-toolsai.jupyter public API
                                 ▼
                     notebook cells, outputs, kernel status

Las interacciones con el kernel usan la API pública documentada ms-toolsai.jupyter (kernel.executeCode, comandos de interrupción/reinicio, comandos de listado de variables/pip) con respaldo de comandos; el seguimiento de la ejecución depende de workspace.onDidChangeNotebookDocument.

Desarrollo

npm install
npm run compile      # typecheck
npm run lint
npm run build        # esbuild bundle
npm run smoke        # local protocol smoke test (vscode stubbed)
npx @vscode/vsce package

Referencias

• Model Context Protocol — transporte Streamable HTTP, especificación 2025-11-25

• microsoft/vscode-copilot-chat (MIT) — resumen de variables, presupuestos de truncamiento y patrones de filtrado por símbolos

• SMARK OpenCode IDE Bridge — comprobaciones previas del kernel mediante la API pública de Jupyter, respaldo de comandos de interrupción/reinicio, seguimiento de finalización basado en eventos

• kriss-spy/opencode-jupyter — concepto original de puente HTTP

Licencia

MIT