Colab-MCP

Colab-MCP

Um servidor MCP que permite a um agente de IA (Claude, ou qualquer cliente MCP) usar o Google Colab de ponta a ponta: criar e encerrar runtimes GPU/TPU, executar código, trabalhar em notebooks célula por célula, iniciar trabalhos longos em segundo plano e mover arquivos e pastas para dentro e para fora da VM.

É uma camada fina e segura sobre o Colab CLI oficial do Google (google-colab-cli). Não reimplementa o Colab e não depende de uma aba do navegador.

🇪🇸 Resumen en español al final de este archivo.

Status

• Testado contra um CLI simulado (118 verificações, mais 129 para Drive contra uma API do Drive simulada, 28 para a montagem do Drive e 17 para limpeza local; tests/): um cliente MCP real conversa com o servidor via stdio e o código que normalmente roda na VM é executado de verdade em uma pasta sandbox.
• Ainda não validado contra o Colab ao vivo. O login e uma primeira execução real são os próximos passos; comportamentos que o CLI não documenta (listados em Known unknowns) estão sinalizados abaixo.
• Apenas Linux e macOS (o Colab CLI não suporta Windows).

Ferramentas (42 + 8 ferramentas opcionais de Drive)

Área	Ferramentas
Runtimes	colab_new, colab_ensure_session, colab_sessions, colab_status, colab_runtime_info, colab_restart_kernel, colab_url, colab_usage, colab_stop, colab_install
Executar código	colab_exec (código ou arquivo; o estado do kernel persiste entre chamadas), colab_run (uso único: VM nova → script → liberação)
Notebooks (.ipynb local)	colab_notebook_create, _list, _read, _add_cell, _edit_cell, _delete_cell, _move_cell, _clear_outputs, _run_cell, _run_all, _to_script, _delete
Trabalhos longos	colab_job_start, _status, _logs, _cancel, _list
Arquivos	colab_upload, colab_download, colab_upload_dir, colab_download_dir, colab_ls, colab_rm, colab_log
Drive na VM	colab_drive_status, colab_drive_mount_start, colab_drive_mount_finish, colab_drive_project_dir (veja Projetos grandes e Drive)
Espaço local	colab_local_footprint, colab_local_cleanup (veja Onde as coisas ficam)

Fluxos típicos:

• Interativo: colab_ensure_session(gpu="T4") → colab_notebook_create → adicionar células → colab_notebook_run_cell uma a uma (as variáveis persistem) → ler saídas → colab_stop.
• Em lote: colab_upload_dir → colab_job_start("python -u train.py") → verificar colab_job_logs → colab_download_dir → colab_stop.

Projetos e notebooks do Google Drive são um recurso separado e opcional (abaixo). Deliberadamente não incluídos em lugar nenhum: login por ferramenta, colab auth, repl, console, ssh, edit. Eles são interativos e não funcionam por meio de uma chamada de ferramenta.

Modelo de segurança

• Caminhos locais são restritos a COLAB_MCP_WORKDIR. ../, caminhos absolutos e symlinks que escapam são rejeitados antes de qualquer execução.
• Segredos nunca chegam ao modelo. COLAB_MCP_ENV_FILE aponta para um arquivo NAME=value local. O modelo apenas passa nomes (secrets=["OPENROUTER_API_KEY"]); os valores vão para o kernel com --env e são removidos de todo resultado. Limite conhecido: enquanto o comando roda, o valor fica visível para outros usuários locais na lista de processos, porque o CLI o recebe como argumento.
• Sem shell. O CLI é executado com uma lista de argumentos. Nomes de sessão, tipos de GPU, especificadores de pacotes e IDs de trabalho são validados. Tudo que é controlado pelo usuário e embutido no código para a VM passa por repr().
• Transferências de pastas são protegidas. Uploads ignoram .git, caches, symlinks e prováveis segredos (.env, *.pem, *.key…); downloads rejeitam arquivos com caminhos que escapam do destino (zip-slip) ou que excedem um limite de tamanho.
• Sem exclusões definitivas no seu computador. colab_notebook_delete move o arquivo para .colab-mcp-trash/. colab_rm só toca na VM e recusa caminhos semelhantes à raiz.
• A saída é limitada a COLAB_MCP_MAX_OUTPUT caracteres, e códigos de cor do terminal (tracebacks) são removidos.
• O código que você executa roda nas máquinas do Google sob sua conta e gasta suas unidades de computação. Encerre sessões que não precisar mais.

Projetos grandes e Drive na VM

Para conjuntos de dados grandes, checkpoints ou resultados que precisam sobreviver à sessão, monte o Google Drive na VM. Isso é separado do recurso opcional "Drive notebooks" abaixo e usa o login próprio do Colab CLI.

1. Monte pelo chat, sem terminal. colab_drive_mount_start executa o colab drivemount oficial em um pseudo-terminal (o CLI em si nunca abre navegador; ele apenas imprime um link e espera Enter), abre a página de aprovação do Google no seu navegador. O link não é repetido no chat (contém o e-mail da sua conta); ele só é retornado se o navegador não puder ser aberto ou com show_link=true. Você clica em Permitir (o agente nunca vê credenciais ou códigos) e avisa o agente; colab_drive_mount_finish então envia o Enter que o CLI estava esperando e colab_drive_status confirma. Apenas links https://*.google.com são abertos, uma montagem pendente é encerrada após 15 minutos, e há no máximo uma por sessão. Se preferir, colab drivemount -s SESSION em um terminal ainda funciona. Montar dá ao código que roda naquela VM acesso a todo o seu Drive (o Colab não consegue limitar o escopo); monte apenas quando precisar e encerre a sessão depois.
2. O agente chama colab_drive_project_dir("my-project"), que cria /content/drive/MyDrive/Colab-MCP/my-project e retorna o caminho. Conjuntos de dados, checkpoints e saídas vão para lá.
3. Encerre a sessão ao terminar. Os arquivos naquela pasta do Drive permanecem; todo o resto na VM é perdido.

Proteção: as ferramentas de arquivo (colab_upload*, colab_download*, colab_ls, colab_rm) recusam qualquer caminho do Drive fora de /content/drive/MyDrive/Colab-MCP/ (nome da pasta configurável com COLAB_MCP_DRIVE_PROJECTS), incluindo .., truques relativos e de maiúsculas/minúsculas. colab_drive_status nunca lista seus arquivos.

Risco residual, dito claramente: uma vez que o Drive está montado, qualquer código que rode na VM (colab_exec, colab_run, trabalhos, células de notebook) pode ler e alterar todo o seu Drive; a proteção de caminho cobre apenas as ferramentas de arquivo deste servidor, e ela não consegue ver symlinks criados na VM. Monte apenas quando precisar, revise o código que executa e encerre a sessão depois.

Onde as coisas ficam (e o quanto pouco permanece no seu computador)

Onde	O quê	Por quê
Disco da VM do Colab (cerca de 200 GB livres observados em uma T4 ⚠️ não garantido)	Conjuntos de dados, treinamento, qualquer coisa pesada	Rápido, grátis, some quando a sessão encerra
Drive, pasta Colab-MCP/<project>/	Notebooks e resultados que precisam persistir	Sobrevive às sessões; a única parte do Drive que esta ferramenta consegue ver
Seu computador	Quase nada: uma cópia de trabalho temporária enquanto você edita um notebook	Limpeza automática (abaixo)

Regras de espaço local (footprint.py):

• Zips de transferência são removidos logo após o uso e varridos após 1 hora; gráficos salvos após 2 dias (COLAB_MCP_IMAGE_DAYS); notebooks "excluídos" localmente após 7 dias (COLAB_MCP_TRASH_DAYS, 0 = manter); cópias de trabalho de notebooks do Drive após 24 h (COLAB_MCP_DRIVE_COPY_HOURS, 0 = manter) e imediatamente ao salvar. A varredura roda quando o servidor inicia e em colab_local_cleanup.
• Apenas arquivos dentro de .colab-mcp/ e .colab-mcp-trash/ são removidos. Symlinks não são seguidos. Seus próprios notebooks e dados nunca são tocados.
• Proteções antes de downloads: pelo menos COLAB_MCP_MIN_FREE_GB (padrão 5) devem permanecer livres no disco e a pasta de trabalho não pode exceder COLAB_MCP_WORKDIR_MAX_GB (padrão 20, 0 = sem limite). colab_local_footprint mostra os números. Mantenha dados grandes na VM ou no Drive e baixe apenas resultados.

Google Drive: projetos e notebooks (opt-in)

Desativado por padrão. Com COLAB_MCP_DRIVE=1 (o instalador define quando você configura o Drive) estas ferramentas aparecem, e apenas estas:

Ferramenta	O que faz
drive_sign_in	Abre uma janela do navegador no seu computador onde você clica em Permitir. Nenhum código ou token passa pelo chat
drive_project_create / drive_project_list	Uma pasta por projeto Colab dentro de Colab-MCP. Pastas podem ser criadas, nunca excluídas ou renomeadas
drive_notebook_create	Cria um notebook (iniciador vazio, ou um .ipynb local com saídas removidas), opcionalmente dentro de um projeto
drive_notebook_list	Lista os notebooks que este servidor criou
drive_notebook_open / drive_notebook_save	Baixa um notebook para uma cópia local temporária, edita com as ferramentas colab_notebook_*, escreve o conteúdo de volta no mesmo arquivo. Salvar remove a cópia local
drive_notebook_delete	Move um deles para a lixeira do Drive (nunca permanente)

Layout no seu Drive: Colab-MCP/<project>/<notebook>.ipynb. A permissão do Google (drive.file) alcança apenas arquivos e pastas que este aplicativo criou, então sua pasta "Colab Notebooks" existente e todo o resto permanecem invisíveis para ele.

Uma skill que mantém o agente exatamente nisso está em skills/colab-drive-notebooks/SKILL.md: copie essa pasta para ~/.claude/skills/ (Claude Code) ou adicione como skill no seu cliente.

Quem é responsável pelo quê

Ninguém compartilha credenciais. Cada usuário faz login por si, e o token vive apenas no próprio disco. Você escolhe uma vez entre dois clientes OAuth (abaixo); este projeto nunca vê seu token. O modelo nunca vê link de login, código ou token.

Início rápido (todo usuário)

bash install.sh pergunta "Configurar Drive agora?", executa a escolha única abaixo e registra o servidor com as ferramentas de Drive habilitadas. Manualmente:

git clone https://github.com/amgallego8/Colab-MCP ~/Colab-MCP && cd ~/Colab-MCP
uv sync
uv run colab-cli-mcp-drive login     # asks once how you want to sign in, remembers it, signs you in

login guia você na criação do seu próprio cliente "Desktop app" do Google Cloud (cerca de 10 minutos, uma vez, grátis; passos abaixo). Quando você dá o caminho do JSON baixado, ele o armazena para você (0600). Você responde ao Google pelo seu projeto. Depois disso, o login é só: um link abre no navegador, você clica em Permitir, pronto. Não há código para colar.

Nenhum cliente compartilhado de um clique é enviado ainda. Se este repositório alcançar 1.000 estrelas, o mantenedor pretende publicar um (um cliente pronto para que o login não exija configuração alguma do Google Cloud). Isso é um plano, não uma promessa. O código para isso já existe: se um build enviar colab_cli_mcp/shared_client.json, login oferece um menu com compartilhado e próprio.

O cliente compartilhado nunca é usado sem uma escolha explícita (uma resposta no terminal ou --shared). Sua escolha é lembrada em ~/.config/colab-mcp/drive/preference.json. A partir daí, quando uma ferramenta de Drive precisar de acesso e não houver token válido (primeiro uso, ou após a expiração de 7 dias de aplicativos em modo Testing), o próprio servidor abre a página de consentimento do navegador e espera seu clique; você então repete a solicitação. Login, escopo drive.file, arquivo de token e todas as proteções são idênticos em ambos os casos.

Depois, deixe a aprovação por chamada ativada para drive_notebook_delete no seu cliente MCP — esse prompt é a confirmação humana real; o servidor não pode forçá-la. uv run colab-cli-mcp-drive status mostra o que está configurado.

Para sair: colab-cli-mcp-drive logout (exclui o token e o revoga no Google), e remova o aplicativo em https://myaccount.google.com/permissions se a revogação não puder ser confirmada.

Criando seu próprio cliente (o que login pede que você faça)

1. No console do Google Cloud, crie um projeto e habilite a Google Drive API (guia).
2. Configure a tela de consentimento / Google Auth Platform (guia): em Audience, escolha External e adicione você mesmo em Test users; em Data Access → Add or Remove Scopes, adicione apenas .../auth/drive.file.
3. Google Auth platform → Clients → Create Client → Desktop app (passos do Google). Baixe o JSON e dê o caminho para login.

Para o mantenedor: publicando um cliente compartilhado

Crie o cliente como acima (idealmente em uma conta e projeto Google dedicados), então coloque o JSON em colab_cli_mcp/shared_client.json e faça o commit de propósito (git add -f; o arquivo é ignorado pelo git por padrão). Segredos de cliente de aplicativo de desktop não são confidenciais por design, mas o projeto, sua tela de consentimento (e-mail de suporte, link de política de privacidade) e quaisquer requisitos de verificação do Google passam a ser seus. Consulte TERMS.md.

Modelo de ameaças (o que isso protege e o que não protege)

Camada	O que ela oferece
Escopo drive.file apenas	O token só pode acessar arquivos que este cliente OAuth criou. Ele não pode ler ou excluir o restante do seu Drive, mesmo que tudo abaixo falhe. O Google classifica este escopo como não sensível.
Seu próprio cliente OAuth	O cliente de outro usuário ou de um fornecedor não pode tocar nos seus arquivos, e você pode revogar o cliente inteiro do seu próprio projeto.
Manipulação de token	Arquivo 0600, recusado se legível por grupo/mundo, recusado se tiver qualquer escopo além de drive.file. Nunca retornado por nenhuma ferramenta. Separado do token do CLI do Colab (que tem escopos mais amplos).
Superfície de ferramentas	Criar pastas; criar / listar / abrir / salvar / mover para a lixeira notebooks que este servidor criou. Sem exclusão permanente, sem exclusão de pastas, sem compartilhamento, sem permissões, sem leitura de outros arquivos, sem consultas ou ids de forma livre. Um teste afirma que nenhuma requisição DELETE e nenhum endpoint de permissões/exportação/cópia é jamais usado.
Guardas de arquivo (abrir, salvar, excluir)	O arquivo deve carregar o marcador deste servidor, ser um notebook Colab, ser de sua propriedade, estar diretamente na pasta do aplicativo ou em uma de suas pastas de projeto, e não estar na lixeira. Excluir também exige redigitar o nome exato. Salvar altera apenas o conteúdo: nunca nome, local ou compartilhamento.
Limites e rastreamento	Por hora: 20 criações de notebooks, 10 pastas de projeto, 60 salvamentos, 5 exclusões, 6 tentativas de login (COLAB_MCP_DRIVE_MAX_CREATES_PER_HOUR, _MAX_PROJECTS_PER_HOUR, _MAX_SAVES_PER_HOUR, _MAX_DELETES_PER_HOUR, _MAX_LOGINS_PER_HOUR); registro de auditoria somente de acréscimo (audit.log, 0600) que nunca armazena conteúdo.
Higiene de conteúdo	Notebooks enviados de um arquivo perdem suas saídas; salvamentos mantêm saídas (desative com keep_outputs=False). Qualquer envio ou salvamento é recusado se contiver um valor do seu arquivo de segredos. Nomes lidos de volta do Drive têm caracteres de controle e bidi removidos e são rotulados como dados.

Riscos residuais, declarados claramente. "Completamente seguro" não é uma afirmação que alguém possa fazer; isto é o que resta:

• Um agente com injeção de prompt ou enganado ainda pode criar notebooks inúteis (com limite de taxa) ou mover para a lixeira um notebook criado por este servidor se você aprovar a chamada. Eles permanecem recuperáveis na lixeira do Drive.
• A verificação por confirmação de nome evita acidentes, não um modelo determinado a repetir o nome; o prompt de aprovação humana no seu cliente é o controle real.
• Qualquer pessoa que possa ler os arquivos da sua conta de usuário pode usar seu token até você sair. Criptografia de disco e conta bloqueada são responsabilidade sua.
• Notebooks que você cria podem conter código que será executado depois no Colab com sua conta; revise o que você abre.
• No modo Testing, o Google expira tokens de atualização após 7 dias para aplicativos externos, então você pode precisar fazer login novamente semanalmente.
• Se uma pasta do Drive chamada Colab-MCP também for criada por código em execução em uma VM com Drive montado, o Drive pode acabar com duas pastas com esse nome que esta ferramenta trata separadamente (⚠️ não verificado). Prefira uma rota por projeto.
• Ainda não testado contra o Google Drive real (veja Unknowns conhecidos).

Env: COLAB_MCP_DRIVE (ativar), COLAB_MCP_DRIVE_COPY_HOURS, COLAB_MCP_DRIVE_DIR (padrão ~/.config/colab-mcp/drive), COLAB_MCP_DRIVE_CLIENT, COLAB_MCP_DRIVE_TOKEN, COLAB_MCP_DRIVE_AUDIT, COLAB_MCP_DRIVE_FOLDER (padrão Colab-MCP).

Instalação

Mais rápido: bash install.sh (macOS/Linux). Ele pergunta antes de instalar qualquer coisa, faz login no Colab e registra o servidor com o Claude Code (ou imprime a configuração do Claude Desktop). Os passos manuais estão abaixo.

# 1. uv and the official CLI
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install google-colab-cli

# 2. Sign in ONCE (open the link, paste the code)
colab sessions

# 3. This server
git clone https://github.com/amgallego8/Colab-MCP ~/Colab-MCP

Arquivo de segredos opcional (fora de qualquer repositório, legível apenas por você):

mkdir -p ~/.config/colab-mcp
printf 'OPENROUTER_API_KEY=your-key-here\n' > ~/.config/colab-mcp/secrets.env
chmod 600 ~/.config/colab-mcp/secrets.env

Registre no Claude Code:

claude mcp add colab-cli \
  -e COLAB_MCP_WORKDIR="$HOME/colab-work" \
  -e COLAB_MCP_ENV_FILE="$HOME/.config/colab-mcp/secrets.env" \
  -- uv run --directory ~/Colab-MCP colab-cli-mcp

Registre no Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "colab-cli": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/YOU/Colab-MCP", "colab-cli-mcp"],
      "env": {
        "COLAB_MCP_WORKDIR": "/Users/YOU/colab-work",
        "COLAB_MCP_ENV_FILE": "/Users/YOU/.config/colab-mcp/secrets.env"
      }
    }
  }
}

Cada pessoa que usar repete esses passos com sua própria conta Google: o token de login é pessoal e não deve ser compartilhado.

Variáveis de ambiente

Variável	Padrão	Finalidade
COLAB_MCP_WORKDIR	diretório atual	A única pasta local que o servidor toca
COLAB_MCP_ENV_FILE	—	Arquivo NAME=value com segredos
COLAB_MCP_AUTH	padrão do CLI	oauth2 ou adc (o --auth do CLI)
COLAB_MCP_MAX_OUTPUT	20000	Máximo de caracteres retornados por chamada
COLAB_MCP_MAX_UPLOAD_MB	100	Limite de upload por arquivo/zip (o CLI envia um arquivo em uma única requisição)
COLAB_MCP_MAX_DOWNLOAD_MB	1024	Limite para downloads de diretórios descompactados
COLAB_BIN	colab	Caminho para o executável do CLI
COLAB_MCP_MIN_FREE_GB	5	Espaço livre em disco que deve permanecer após um download
COLAB_MCP_WORKDIR_MAX_GB	20	Orçamento para a pasta de trabalho (0 = sem limite)
COLAB_MCP_IMAGE_DAYS / COLAB_MCP_TRASH_DAYS / COLAB_MCP_DRIVE_COPY_HOURS	2 / 7 / 24	Idade após a qual gráficos salvos, notebooks movidos para a lixeira local e cópias de trabalho do Drive são limpos (0 = manter lixeira/cópias)
COLAB_MCP_DRIVE_PROJECTS	Colab-MCP	A única pasta do Drive (sob MyDrive) que as ferramentas de arquivo podem usar quando o Drive está montado na VM

Como os notebooks funcionam

Notebooks são arquivos .ipynb comuns dentro do diretório de trabalho, editados localmente com nbformat, então editar não precisa de runtime. colab_notebook_run_cell envia uma célula para o runtime através de colab exec; o kernel mantém suas variáveis entre chamadas, e a saída da célula (texto, erros, um gráfico exibido) é gravada de volta no notebook. Células são endereçadas por id (estável) ou índice. Gráficos são salvos em .colab-mcp/images/.

colab_exec com um arquivo .ipynb executa o notebook inteiro e o CLI salva <name>_output.ipynb ao lado dele.

Unknowns conhecidos (a confirmar contra o Colab real)

Estes vêm da leitura do código-fonte e da documentação do CLI, não da execução:

• Variáveis do kernel persistindo entre chamadas exec (o código-fonte reutiliza o mesmo id de kernel, então deve funcionar).
• A detecção de sucesso/falha de célula depende de get_ipython().run_cell estar disponível no kernel do Colab.
• Se --output-image salva todas as formas de imagem (ele lida com dados de exibição PNG/JPEG).
• O limite real de tamanho de upload (o CLI envia um arquivo em uma única requisição; o limite de 100 MB é um palpite conservador).
• Se os Segredos do Colab (userdata) são legíveis no kernel ao executar pelo CLI — não documentado. Use secrets=[...] em vez disso.
• Google Drive (opt-in, veja abaixo): o tipo MIME do Colab application/vnd.google.colaboratory não foi encontrado na documentação do Google Drive. O servidor verifica o que o Drive armazenou após cada criação e desfaz se diferir, mas isso ainda não foi executado contra o Drive real.
• Se um aplicativo Google Cloud que permanece não verificado pode ser usado por seu proprietário sem a expiração de token de atualização de 7 dias do modo "Testing" (a documentação do Google diz que tokens de atualização de aplicativos externos em Testing expiram após 7 dias; as regras para aplicativos não verificados "Em produção" não foram confirmadas).

Desenvolver

pip install "mcp<2" nbformat google-auth google-auth-oauthlib requests
python tests/test_server.py   # the Colab tools, with a simulated CLI
python tests/test_drive.py    # the Drive tools, with a simulated Drive API
python tests/test_footprint.py # local cleanup and disk guards
python tests/test_mount.py     # Drive mount from the chat, with a simulated CLI

O pin do SDK mcp<2 é intencional: 2.x renomeou FastMCP para MCPServer.

Termos de uso e privacidade

Consulte TERMS.md: nenhum servidor e nenhuma coleta de dados pelo mantenedor, o que é armazenado localmente, responsabilidades do usuário, quem responde ao Google sob cada opção de login e a cláusula de ausência de garantia.

Licença

Apache License 2.0 — consulte LICENSE. Copyright 2026 dos contribuidores do Colab-MCP (amgallego8). O CLI oficial do Colab que este projeto encapsula é um trabalho separado, também Apache-2.0, e não está incluído aqui.

---

Resumen en español

Servidor MCP para que un agente use Google Colab de punta a punta: crear y detener runtimes con GPU/TPU, ejecutar código, trabajar en cuadernos celda por celda, lanzar trabajos largos en segundo plano y mover archivos y carpetas hacia y desde la VM. Envuelve el Colab CLI oficial de Google.

• Estado: probado con un CLI simulado (92 comprobaciones). Falta validar con Colab real (ver «Known unknowns»).
• Seguridad: las rutas locales quedan confinadas a COLAB_MCP_WORKDIR; las claves viven en un archivo local y nunca se devuelven al modelo; no hay shell; los borrados de cuadernos van a una papelera recuperable.
• Instalación: cada persona repite los pasos de «Install» con su propia cuenta de Google. El token de sesión es personal.
• Google Drive (opcional): carpetas de proyecto y cuadernos de Colab en Colab-MCP/<proyecto>/ de tu Drive (crear, abrir, guardar, borrar a la papelera), nada más. Eliges una sola vez entre el cliente compartido y el tuyo; después el propio servidor abre el navegador cuando haga falta y tú solo pulsas «Permitir» (el código y el token nunca pasan por el chat). El permiso es drive.file: solo ve lo que esta herramienta crea. Tu computador queda casi vacío: los temporales se limpian solos y lo pesado va al disco de la VM o a Drive. Hay una skill (skills/colab-drive-notebooks) que limita al agente a eso. Ver «Google Drive» y el modelo de amenazas, con sus riesgos residuales. Aún sin probar contra Drive real.
• Costo: lo que ejecutes consume tus unidades de cómputo de Colab. Detén las sesiones que no uses.