Jupyter MCP Server

📖 Documentación  ·  🔧 Herramientas  ·  💬 Comunidad

No hay ningún proceso que ejecutar. Datalayer ahora aloja este servidor por ti en https://mcp.datalayer.run/mcp — un único endpoint para cada agente y cada notebook. Inicia sesión desde tu navegador, aprueba lo que el agente puede hacer, y tu trabajo sigue ejecutándose en el servidor después de que el agente se desconecte.

→ Servidor Jupyter MCP alojado

Un solo comando para conectar Claude Code, con /datalayer:notebook, /datalayer:run y /datalayer:status incluidos:

/plugin marketplace add datalayer/jupyter-mcp-server
/plugin install datalayer

→ Plugin de Datalayer para Claude Code

Gratuito y de código abierto, licencia BSD 3-Clause — apúntalo a cualquier Jupyter que ya ejecutes, local o JupyterHub, sin necesidad de cuenta.

Construido y mantenido por Datalayer, donde el mismo servidor impulsa Notebooks siempre activos con Code Sandboxes con GPU y ejecución duradera — para que tu agente siga trabajando con tus datos cuando tu portátil no lo hace.

No hay tokens que copiar y pegar. Un agente que se encuentra con este servidor sin autenticación recibe instrucciones sobre dónde autenticarse, abre tu navegador, y tú inicias sesión en Datalayer como tú mismo. El agente nunca ve tu contraseña — recibe un token limitado a lo que has aprobado, y puedes desconectar un agente sin afectar a los demás.

Lo que cada agente puede hacer son dos decisiones separadas: los ámbitos que apruebas (notebooks:read, notebooks:write, code:execute, data:read) indican qué tipo de operación puede realizar, y tus propios permisos de Datalayer siguen indicando qué notebooks puede tocar. Un agente nunca puede acceder a un notebook al que tú no puedas.

Los tokens de acceso personal siguen funcionando y siguen siendo la vía más sencilla para una CLI o un script. → OAuth e identidad

Fija code-sandboxes para que coincida con tu jupyter-mcp-server. La variante de sandbox jupyter pasó a llamarse jupyter-server en code-sandboxes 1.1.1, y los dos paquetes deben coincidir en el nombre.

# On 1.5.0 or later
pip install "jupyter-mcp-server>=1.5.0" "code-sandboxes>=1.1.1"

# Staying on an earlier jupyter-mcp-server
pip install "jupyter-mcp-server<1.5.0" "code-sandboxes<=1.0.9"

Un servidor antiguo con un code-sandboxes más reciente se instala correctamente y luego falla en la primera ejecución con Unknown sandbox variant: jupyter. → Notas de la versión

Jupyter MCP Server 2 se ejecuta sobre el MCP Python SDK 2 (mcp>=2,<3), la primera versión principal del SDK. Nada cambia en cómo inicias o configuras el servidor, en las herramientas, ni para los clientes MCP que se conectan a él — el protocolo se negocia con cada cliente como antes. Lo que cambia es el entorno de Python:

Ambos están fijados en el paquete, así que pip lo resuelve; un entorno que tenga otro paquete que aún fije mcp<2 debe permanecer en jupyter-mcp-server<2 hasta que ese paquete cambie. ¿Estás escribiendo una extensión o un verificador de tokens personalizado contra el SDK? Consulta las notas de la versión para ver las importaciones renombradas.

--provider ahora es --document-provider (variable de entorno PROVIDER → DOCUMENT_PROVIDER).

Solo elegía dónde viven los documentos del notebook — jupyter para la API de colaboración de un Jupyter Server, datalayer para el espaciador de Datalayer — mientras que el nombre antiguo y su texto de ayuda sugerían que también elegía dónde se ejecuta el código. La ejecución se elige por separado, con --sandbox-variant (jupyter-server, datalayer, daytona, e2b, coreweave, cloudflare, kaggle, google-colab, monty, modal).

Nada se rompe en v1.3.2: --provider sigue aceptándose como alias, PROVIDER sigue leyéndose, y una carga útil de /connect que contenga "provider" sigue entendiéndose. Cambia a los nuevos nombres cuando te convenga — los antiguos están obsoletos, no eliminados.

📖 Tabla de Contenidos

• Características Clave
• Descripción General de MCP
• Primeros Pasos
• Variantes de Sandbox
• Mejores Prácticas
• Contribuciones
• Recursos

🚀 Características Clave

• ⚡ Control en tiempo real: Visualiza los cambios del notebook al instante.
• 🔁 Ejecución inteligente: Se ajusta automáticamente cuando falla la ejecución de una celda gracias a la retroalimentación de la salida de la celda.
• 🧠 Consciente del contexto: Entiende el contexto completo del notebook para interacciones más relevantes.
• 📊 Soporte multimodal: Admite diferentes tipos de salida, incluyendo imágenes, gráficos y texto.
• 📚 Soporte multi-notebook: Cambia sin problemas entre varios notebooks.
• 🎨 Integración con JupyterLab: Integración de interfaz mejorada, como la apertura automática de notebooks.
• 🤝 Compatible con MCP: Funciona con cualquier cliente MCP, como Claude Desktop, Cursor, Windsurf y más.
• 🔍 Observabilidad: Sistema de hooks integrado con integración de OpenTelemetry para rastrear llamadas de herramientas y ejecuciones de kernels.

Compatible con cualquier despliegue de Jupyter (local, JupyterHub, ...) y con Datalayer Notebooks alojados, donde los Code Sandboxes vienen con GPUs y la ejecución sobrevive a una desconexión.

🔧 Descripción General de MCP

🔧 Descripción General de Herramientas

Cada herramienta, con sus parámetros, esquema y valor de retorno, se genera a partir de una instantánea en vivo del servidor en ejecución y se publica en jupyter-mcp-server.datalayer.tech/mcp — por lo que nunca está desactualizada respecto al código, cosa que una tabla copiada en este archivo sí estaría.

Se dividen en cuatro grupos:

• Servidor y code sandbox — explora el sistema de archivos de Jupyter, lista kernels, conéctate a un servidor en tiempo de ejecución, y lanza, selecciona y termina code sandboxes.
• Notebooks — abre, crea y cambia entre notebooks, lístalos, lee uno, reinicia su kernel, libéralo.
• Celdas — lee, inserta, elimina, mueve, reordena y edita celdas, quirúrgicamente o por completo, y limpia sus salidas.
• Ejecución — ejecuta una celda o código arbitrario en el backend activo, con salida multimodal y transmisión donde el sandbox lo admita.

Las herramientas de sandbox necesitan la extensión opcional jupyter_mcp_sandboxes; consulta Variantes de Sandbox.

Integración con JupyterLab

Disponible solo cuando el modo JupyterLab está habilitado. Está habilitado por defecto.

En el modo JupyterLab, el servidor también expone comandos de JupyterLab como herramientas MCP a través de jupyter-mcp-tools — notebook_run-all-cells y notebook_get-selected-cell por defecto, con más seleccionables a través de allowed_jupyter_mcp_tools. La lista completa y cómo configurarlo están en la documentación de Herramientas Adicionales.

📝 Descripción General de Prompts

El servidor implementa la característica de prompts de MCP. jupyter-cite cita celdas específicas de un notebook, de la misma manera que @ lo hace en un IDE de codificación o CLI. Los parámetros de entrada y el contenido devuelto están en la documentación de Prompts.

🏁 Primeros Pasos

Para instrucciones completas de configuración—incluyendo transporte Streamable HTTP, ejecución como extensión del servidor Jupyter y configuración avanzada—consulta nuestra documentación. O, comienza rápidamente con JupyterLab y transporte STDIO aquí abajo.

1. Configura Tu Entorno

pip install jupyterlab jupyter-collaboration jupyter-mcp-tools ipykernel

Para confirmar que tu entorno está configurado correctamente:

1. Abre un notebook en JupyterLab
2. Escribe algún contenido en cualquier celda (código o markdown)
3. Observa el indicador de la pestaña: deberías ver una "×" aparecer junto al nombre del notebook, indicando cambios sin guardar
4. Espera unos segundos—la "×" debería cambiar automáticamente a un "●" sin guardar manualmente

Este comportamiento de guardado automático confirma que las funciones de colaboración en tiempo real están funcionando correctamente, lo cual es esencial para la integración del servidor MCP.

2. Inicia JupyterLab

# Start JupyterLab on port 8888, allowing access from any IP and setting a token
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0

Si estás ejecutando notebooks a través de JupyterHub en lugar de JupyterLab como arriba, consulta nuestra guía de configuración de JupyterHub.

3. Configura Tu Cliente MCP Preferido

A continuación, configura tu cliente MCP para conectarse al servidor. Ofrecemos dos métodos principales—elige el que mejor se adapte a tus necesidades:

• 📦 Usando uvx (Recomendado para Inicio Rápido): Un método ligero y rápido usando uv. Ideal para desarrollo local y usuarios primerizos.
• 🐳 Usando Docker (Recomendado para Producción): Un enfoque contenerizado que asegura un entorno consistente y aislado, perfecto para producción o configuraciones complejas.

pip install uv
uv --version
# should be 0.6.14 or higher

{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": ["jupyter-mcp-server@latest"],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "JUPYTER_URL",
        "-e", "JUPYTER_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://host.docker.internal:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "JUPYTER_URL",
        "-e", "JUPYTER_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "--network=host",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

1. Configuración del Puerto: Asegúrate de que el port en tus URLs de Jupyter coincida con el usado en el comando jupyter lab. Para una configuración simplificada, establece esto en JUPYTER_URL.
2. Separación del Servidor: Usa JUPYTER_URL cuando ambos servicios estén en el mismo servidor, o establece variables individuales para despliegues avanzados. Las diferentes variables de URL existen porque algunos despliegues separan el almacenamiento de notebooks (DOCUMENT_URL) de la ejecución del kernel (CODE_SANDBOX_URL).
3. Autenticación: En la mayoría de los casos, los servicios de documentos y code sandbox usan el mismo token de autenticación. Usa JUPYTER_TOKEN para una configuración simplificada o establece DOCUMENT_TOKEN y CODE_SANDBOX_TOKEN individualmente para diferentes credenciales.
4. Ruta del Notebook: El parámetro DOCUMENT_ID especifica la ruta al notebook al que el cliente MCP se conecta por defecto. Debe ser relativa al directorio donde se inició JupyterLab. Si omites DOCUMENT_ID, el cliente MCP puede listar automáticamente todos los notebooks disponibles en el servidor Jupyter, permitiéndote seleccionar uno interactivamente a través de tus prompts.
5. Salida de Imágenes: Establece ALLOW_IMG_OUTPUT a false si tu LLM no admite comprensión multimodal.

Para instrucciones detalladas sobre cómo configurar varios clientes MCP—incluyendo Claude Desktop, VS Code, Cursor, Cline y Windsurf — consulta Configuración de Clientes MCP.

🧩 Variantes de Sandbox

Por defecto, el código se ejecuta a través de la variante code-sandboxes jupyter-server contra un Jupyter Server (SANDBOX_VARIANT=jupyter-server). Establecer SANDBOX_VARIANT a cualquier otro valor utiliza otro motor de code-sandboxes mediante el cliente de kernel simple del sandbox cuando la variante seleccionada expone uno, por lo que las mismas herramientas de notebook pueden ejecutar código en backends adicionales.

La ortografía no es estricta: google_colab, google-colab y GOOGLE-COLAB nombran la misma variante. Los nombres a continuación son los canónicos.

Las características de sandbox las proporciona la extensión opcional jupyter_mcp_sandboxes. Para exponer herramientas de ciclo de vida del sandbox (launch_sandbox, list_sandboxes, use_sandbox, terminate_sandbox) o ejecutar cualquier variante de sandbox que no sea jupyter-server, instálala con pip install jupyter_mcp_sandboxes.

Cada motor tiene su propia página con las credenciales que necesita, las opciones de acelerador que acepta y una configuración de cliente funcional: comienza desde jupyter-mcp-server.datalayer.tech/code-sandboxes.

🧪 Pruebas

Ejecuta la suite de pruebas:

pytest tests/

Variables de entorno requeridas para las pruebas:

• Ninguna para la suite local predeterminada.

Variables de entorno opcionales:

• TEST_MCP_SERVER: conmutador true/false para pruebas de modo servidor MCP independiente (predeterminado true).
• TEST_JUPYTER_SERVER: conmutador true/false para pruebas de modo extensión de Jupyter (predeterminado true).
• DATALAYER_API_KEY: requerida solo para pruebas de humo/integración en la nube de Datalayer.
• DATALAYER_RUN_URL: URL personalizada opcional de sandbox de código de Datalayer para pruebas del motor datalayer.
• SANDBOX_ENVIRONMENT: anulación opcional del entorno en la nube (por ejemplo, ai-agents-env).

✅ Mejores prácticas

• Interactúa con LLMs que admitan entrada multimodal (como Gemini 2.5 Pro) para aprovechar al máximo las capacidades avanzadas de comprensión multimodal.
• Usa un cliente MCP que admita devolver datos de imagen y pueda analizarlos (como Cursor, Gemini CLI, etc.), ya que algunos clientes pueden no admitir esta función.
• Divide tareas complejas (como todo el flujo de trabajo de ciencia de datos) en múltiples subtareas (como limpieza de datos, ingeniería de características, entrenamiento de modelos, evaluación de modelos, etc.) y ejecútalas paso a paso.
• Proporciona indicaciones y reglas claramente estructuradas (👉 Visita nuestras Plantillas de indicaciones para comenzar)
• Proporciona tanto contexto como sea posible (como paquetes ya instalados, explicaciones de campos para conjuntos de datos existentes, directorio de trabajo actual, requisitos detallados de la tarea, etc.).

🤝 Contribuciones

¡Agradecemos contribuciones de todo tipo! Aquí hay algunos ejemplos:

• 🐛 Correcciones de errores
• 📝 Mejoras a funciones existentes
• 🔧 Desarrollo de nuevas funciones
• 📚 Mejoras de documentación y plantillas de indicaciones

Para instrucciones detalladas sobre cómo comenzar con el desarrollo y enviar tus contribuciones, consulta nuestra Guía de contribución.

Nuestros colaboradores

📚 Recursos

¿Buscas publicaciones de blog, videos u otros materiales sobre Jupyter MCP Server?

👉 ¡Visita la sección de Recursos en nuestra documentación para más información!

Si este proyecto te resulta útil, por favor danos una ⭐️

Hecho con ❤️ por Datalayer