Jupyter MCP Server

📖 Documentação  ·  🔧 Ferramentas  ·  💬 Comunidade

Nenhum processo para executar. A Datalayer agora hospeda este servidor para você em https://mcp.datalayer.run/mcp — um único endpoint para cada agente e cada notebook. Entre com seu navegador, aprove o que o agente pode fazer, e seu trabalho continua rodando no servidor após o agente desconectar.

→ Servidor Jupyter MCP Hospedado

Um único comando para conectar o Claude Code, com /datalayer:notebook, /datalayer:run e /datalayer:status por cima:

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

→ Plugin Datalayer para Claude Code

Gratuito e open source, BSD 3-Clause — aponte para qualquer Jupyter que você já execute, local ou JupyterHub, sem necessidade de conta.

Construído e mantido pela Datalayer, onde o mesmo servidor impulsiona Notebooks sempre ativos com Code Sandboxes com GPU e execução durável — para que seu agente continue trabalhando em seus dados quando seu laptop não estiver.

Nenhum token para copiar e colar. Um agente que encontra este servidor sem autenticação é informado onde autenticar, abre seu navegador, e você entra na Datalayer como você mesmo. O agente nunca vê sua senha — ele recebe um token com escopo limitado ao que você aprovou, e você pode desconectar um agente sem afetar os outros.

O que cada agente pode fazer são duas decisões separadas: os escopos que você aprova (notebooks:read, notebooks:write, code:execute, data:read) definem que tipo de operação ele pode realizar, e suas próprias permissões da Datalayer ainda definem quais notebooks ele pode acessar. Um agente nunca pode alcançar um notebook que você não pode.

Tokens de acesso pessoal continuam funcionando e permanecem o caminho mais simples para uma CLI ou script. → OAuth e identidade

Fixar code-sandboxes para corresponder ao seu jupyter-mcp-server. A variante de sandbox jupyter foi renomeada para jupyter-server no code-sandboxes 1.1.1, e os dois pacotes precisam concordar com o nome.

# 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"

Um servidor mais antigo com um code-sandboxes mais novo instala corretamente e falha na primeira execução com Unknown sandbox variant: jupyter. → Notas de versão

Jupyter MCP Server 2 roda no MCP Python SDK 2 (mcp>=2,<3), o primeiro grande lançamento do SDK. Nada muda em como você inicia ou configura o servidor, nas ferramentas, ou para os clientes MCP que se conectam a ele — o protocolo é negociado com cada cliente como antes. O que muda é o ambiente Python:

Ambos estão fixados no pacote, então pip resolve isso; um ambiente com outro pacote que ainda fixa mcp<2 precisa permanecer no jupyter-mcp-server<2 até que esse pacote mude. Escrevendo uma extensão ou um verificador de token personalizado contra o SDK? Veja as notas de versão para os imports renomeados.

--provider agora é --document-provider (variável de ambiente PROVIDER → DOCUMENT_PROVIDER).

Ela apenas escolhia onde os documentos do notebook ficam — jupyter para a API de colaboração de um Jupyter Server, datalayer para o spacer da Datalayer — enquanto o nome antigo e seu texto de ajuda sugeriam que também escolhia onde o código roda. A execução é escolhida separadamente, com --sandbox-variant (jupyter-server, datalayer, daytona, e2b, coreweave, cloudflare, kaggle, google-colab, monty, modal).

Nada quebra na v1.3.2: --provider ainda é aceito como alias, PROVIDER ainda é lido, e um payload /connect carregando "provider" ainda é compreendido. Mude para os novos nomes quando for conveniente — os antigos estão obsoletos, não removidos.

📖 Sumário

• Principais Recursos
• Visão Geral do MCP
• Começando
• Variantes de Sandbox
• Melhores Práticas
• Contribuindo
• Recursos

🚀 Principais Recursos

• ⚡ Controle em tempo real: Veja instantaneamente as mudanças no notebook conforme acontecem.
• 🔁 Execução inteligente: Ajusta automaticamente quando uma execução de célula falha graças ao feedback de saída da célula.
• 🧠 Consciente do contexto: Entende todo o contexto do notebook para interações mais relevantes.
• 📊 Suporte multimodal: Suporta diferentes tipos de saída, incluindo imagens, gráficos e texto.
• 📚 Suporte a múltiplos notebooks: Alterne facilmente entre vários notebooks.
• 🎨 Integração com JupyterLab: Integração aprimorada de UI, como abertura automática de notebooks.
• 🤝 Compatível com MCP: Funciona com qualquer cliente MCP, como Claude Desktop, Cursor, Windsurf e outros.
• 🔍 Observabilidade: Sistema de hooks integrado com integração OpenTelemetry para rastrear chamadas de ferramentas e execuções de kernels.

Compatível com qualquer implantação Jupyter (local, JupyterHub, ...) e com Datalayer Notebooks hospedados, onde os Code Sandboxes vêm com GPUs e a execução sobrevive a uma desconexão.

🔧 Visão Geral do MCP

🔧 Visão Geral das Ferramentas

Cada ferramenta, com seus parâmetros, esquema e valor de retorno, é gerada a partir de um snapshot ao vivo do servidor em execução e publicada em jupyter-mcp-server.datalayer.tech/mcp — para que nunca fique desatualizada em relação ao código, o que uma tabela copiada neste arquivo estaria.

Elas se dividem em quatro grupos:

• Servidor e code sandbox — navegue pelo sistema de arquivos do Jupyter, liste kernels, conecte-se a um servidor em tempo de execução e inicie, selecione e encerre code sandboxes.
• Notebooks — abra, crie e alterne entre notebooks, liste-os, leia um, reinicie seu kernel, libere-o.
• Células — leia, insira, exclua, mova, reordene e edite células, cirurgicamente ou por completo, e limpe suas saídas.
• Execução — execute uma célula ou código arbitrário no backend ativo, com saída multimodal e streaming onde o sandbox suportar.

As ferramentas de sandbox precisam da extensão opcional jupyter_mcp_sandboxes; veja Variantes de Sandbox.

Integração com JupyterLab

Disponível apenas quando o modo JupyterLab está habilitado. Ele é habilitado por padrão.

No modo JupyterLab, o servidor também expõe comandos do JupyterLab como ferramentas MCP através do jupyter-mcp-tools — notebook_run-all-cells e notebook_get-selected-cell por padrão, com mais selecionáveis através de allowed_jupyter_mcp_tools. A lista completa e como configurá-la estão na documentação de Ferramentas Adicionais.

📝 Visão Geral dos Prompts

O servidor implementa o recurso de prompts do MCP. jupyter-cite cita células específicas de um notebook, da mesma forma que @ faz em um IDE de codificação ou CLI. Parâmetros de entrada e conteúdo retornado estão na documentação de Prompts.

🏁 Começando

Para instruções abrangentes de configuração — incluindo transporte Streamable HTTP, execução como extensão do Jupyter Server e configuração avançada — consulte nossa documentação. Ou comece rapidamente com transporte JupyterLab e STDIO aqui abaixo.

1. Configure Seu Ambiente

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

Para confirmar que seu ambiente está configurado corretamente:

1. Abra um notebook no JupyterLab
2. Digite algum conteúdo em qualquer célula (código ou markdown)
3. Observe o indicador da aba: você deve ver um "×" aparecer ao lado do nome do notebook, indicando mudanças não salvas
4. Aguarde alguns segundos — o "×" deve mudar automaticamente para um "●" sem salvar manualmente

Esse comportamento de salvamento automático confirma que os recursos de colaboração em tempo real estão funcionando corretamente, o que é essencial para a integração do servidor MCP.

2. Inicie o 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

Se você estiver executando notebooks através do JupyterHub em vez do JupyterLab como acima, consulte nosso guia de configuração do JupyterHub.

3. Configure Seu Cliente MCP Preferido

Em seguida, configure seu cliente MCP para conectar ao servidor. Oferecemos dois métodos principais — escolha o que melhor atende às suas necessidades:

• 📦 Usando uvx (Recomendado para Início Rápido): Um método leve e rápido usando uv. Ideal para desenvolvimento local e usuários de primeira viagem.
• 🐳 Usando Docker (Recomendado para Produção): Uma abordagem containerizada que garante um ambiente consistente e isolado, perfeito para produção ou configurações complexas.

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. Configuração de Porta: Garanta que o port nas suas URLs do Jupyter corresponda ao usado no comando jupyter lab. Para configuração simplificada, defina isso em JUPYTER_URL.
2. Separação de Servidor: Use JUPYTER_URL quando ambos os serviços estiverem no mesmo servidor, ou defina variáveis individuais para implantações avançadas. As diferentes variáveis de URL existem porque algumas implantações separam o armazenamento de notebooks (DOCUMENT_URL) da execução do kernel (CODE_SANDBOX_URL).
3. Autenticação: Na maioria dos casos, os serviços de documentos e code sandbox usam o mesmo token de autenticação. Use JUPYTER_TOKEN para configuração simplificada ou defina DOCUMENT_TOKEN e CODE_SANDBOX_TOKEN individualmente para credenciais diferentes.
4. Caminho do Notebook: O parâmetro DOCUMENT_ID especifica o caminho para o notebook ao qual o cliente MCP se conecta por padrão. Ele deve ser relativo ao diretório onde o JupyterLab foi iniciado. Se você omitir DOCUMENT_ID, o cliente MCP pode listar automaticamente todos os notebooks disponíveis no servidor Jupyter, permitindo que você selecione um interativamente através de seus prompts.
5. Saída de Imagem: Defina ALLOW_IMG_OUTPUT para false se seu LLM não suportar compreensão multimodal.

Para instruções detalhadas sobre como configurar vários clientes MCP — incluindo Claude Desktop, VS Code, Cursor, Cline e Windsurf — veja Configuração de Cliente MCP.

🧩 Variantes de Sandbox

Por padrão, o código é executado por meio da variante code-sandboxes jupyter-server contra um Jupyter Server (SANDBOX_VARIANT=jupyter-server). Definir SANDBOX_VARIANT para qualquer outro valor usa outro mecanismo de code-sandboxes por meio do cliente de kernel simples do sandbox quando a variante selecionada expõe um, para que as mesmas ferramentas de notebook possam executar código em backends adicionais.

A grafia não é rigorosa: google_colab, google-colab e GOOGLE-COLAB nomeiam a mesma variante. Os nomes abaixo são os canônicos.

Os recursos de sandbox são fornecidos pela extensão opcional jupyter_mcp_sandboxes. Para expor ferramentas de ciclo de vida do sandbox (launch_sandbox, list_sandboxes, use_sandbox, terminate_sandbox) ou executar qualquer variante de sandbox não jupyter-server, instale-a com pip install jupyter_mcp_sandboxes.

Cada engine tem sua própria página com as credenciais necessárias, as opções de acelerador que aceita e uma configuração de cliente funcional — comece em jupyter-mcp-server.datalayer.tech/code-sandboxes.

🧪 Testes

Execute a suíte de testes:

pytest tests/

Variáveis de ambiente necessárias para os testes:

• Nenhuma para a suíte local padrão.

Variáveis de ambiente opcionais:

• TEST_MCP_SERVER: alternância true/false para testes de modo servidor MCP autônomo (padrão true).
• TEST_JUPYTER_SERVER: alternância true/false para testes de modo extensão Jupyter (padrão true).
• DATALAYER_API_KEY: necessária apenas para testes de smoke/integração na nuvem Datalayer.
• DATALAYER_RUN_URL: URL personalizada opcional de sandbox de código Datalayer para testes do engine datalayer.
• SANDBOX_ENVIRONMENT: substituição opcional de ambiente de nuvem (por exemplo, ai-agents-env).

✅ Boas Práticas

• Interaja com LLMs que suportam entrada multimodal (como Gemini 2.5 Pro) para aproveitar totalmente os recursos avançados de compreensão multimodal.
• Use um cliente MCP que suporte retorno de dados de imagem e possa analisá-los (como Cursor, Gemini CLI, etc.), pois alguns clientes podem não suportar esse recurso.
• Divida tarefas complexas (como todo o fluxo de trabalho de ciência de dados) em várias subtarefas (como limpeza de dados, engenharia de recursos, treinamento de modelo, avaliação de modelo, etc.) e execute-as passo a passo.
• Forneça prompts e regras claramente estruturados (👉 Visite nossos Modelos de Prompt para começar)
• Forneça o máximo de contexto possível (como pacotes já instalados, explicações de campos para conjuntos de dados existentes, diretório de trabalho atual, requisitos detalhados da tarefa, etc.).

🤝 Contribuições

Aceitamos contribuições de todos os tipos! Aqui estão alguns exemplos:

• 🐛 Correções de bugs
• 📝 Melhorias em recursos existentes
• 🔧 Desenvolvimento de novos recursos
• 📚 Melhorias na documentação e modelos de prompt

Para instruções detalhadas sobre como começar com o desenvolvimento e enviar suas contribuições, consulte nosso Guia de Contribuição.

Nossos Contribuidores

📚 Recursos

Procurando postagens de blog, vídeos ou outros materiais sobre o Jupyter MCP Server?

👉 Visite a seção de Recursos em nossa documentação para mais!

Se este projeto for útil para você, por favor nos dê uma ⭐️

Feito com ❤️ por Datalayer