GOOGLE COLAB · MCP CONNECTION
AI에게 요청하고,
Colab에서 실행한다
AI가 코드를 쓰고, 셀을 실행하고, 결과를 읽는다. 내 컴퓨터의 AI 도구와 브라우저의 Colab 노트북을 연결해 실습을 이어간다.
학부 인공지능 · 대학원 실습 공통 안내 · 확인일 2026-09-29
COLABconnection-check.ipynb
[ ]
내 컴퓨터의 AI 도구
“새 연습 노트북에서 6 × 7을 계산해 줘.”
↓
Colab MCP
AI의 요청을 노트북 도구에 전달
[1]
print(6 * 7)42
HAND THIS TO YOUR AGENT
Claude·Antigravity에도 같은 안내를 전달한다
로컬 명령과 설정 파일을 다룰 수 있는 AI 도구에서 아래 요청문을 사용한다. 도구를 잘 모르겠다면 ‘AI가 확인’을 선택한다.
AI가 로컬 실행, STDIO MCP, 도구 목록 갱신 지원을 먼저 확인한다.
AI가 링크를 읽지 못하면 안내 파일을 첨부하거나 설정 안내 전체를 복사해 요청문과 함께 전달한다.
이 주소는 설정 안내 페이지다. 원격 MCP 서버 주소를 넣는 칸에 붙여 넣지 않는다. AI와 대화하는 입력창에 전달한다. MCP 서버는 학생 컴퓨터에서 실행되고, Google 로그인과 브라우저의 연결 확인은 학생이 직접 진행한다.
내가 준비할 세 가지
내가 확인한 준비 항목 0/3. 실제 연결 여부는 테스트 셀로 확인한다.
AI가 확인할 준비 도구
Git, uv/uvx, 서버 실행용 Python 3.13 이상. 이 Python은 내 컴퓨터에서 MCP 서버를 실행하기 위한 버전이며 Colab 런타임의 Python을 바꾸라는 뜻은 아니다.
현재 공식 저장소의 요구 조건이다. AI용 안내는 설치할 때 최신 요구 버전을 다시 확인하도록 한다. 요구 버전 확인 ↗
Google이 안내하는 지원 예시는 Gemini CLI, Claude Code, Windsurf다. Claude Desktop·Antigravity·Codex 등 다른 도구도 로컬 STDIO MCP와 notifications/tools/list_changed를 지원하는지 확인한다. 공식 지원 조건 ↗
설정 파일을 만든 다음이 중요하다
AI 도구에 서버를 등록한다
설정 항목이 저장되고 서버가 시작되는지 확인한다. 필요한 경우 AI 도구를 다시 연다.
Colab 브라우저 연결을 연다
AI가
open_colab_browser_connection도구를 호출한다. 열린 브라우저에서 로그인하고 연결 안내를 진행한다. 연결에 시간이 걸렸다면 로그인 후 다시 시도한다.노트북 도구로 셀을 실행한다
연결 후 갱신된 도구 목록을 읽고 새 연습 노트북에서
print(6 * 7)을 실행한다. Colab 셀 출력이 42인 것까지 확인해야 연결 완료다.
이 페이지를 읽는 AI 도구에게
AI용 설정 안내 원문(Markdown)에 환경 확인, 도구별 등록, 검증, 오류 해결 순서가 있다. 사용자가 연결을 요청했다면 이 안내와 공식 저장소를 읽고 가능한 설정을 진행한다.
이 웹페이지 자체가 설치를 실행하지는 않는다. 로컬 실행 권한이 없거나 필수 기능이 없는 도구는 그 제한을 알리고, 학생이 같은 컴퓨터에서 사용할 수 있는 지원 도구로 이어갈 방법을 설명한다. 브라우저 연결 전에는 ‘설정 완료’와 ‘노트북 연결 완료’를 구분한다.
공유할 주소
https://hufs-ai-lecture.pages.dev/ai/colab-mcp
AI용 설정 안내 전체 펼치기
링크를 읽을 수 없는 도구는 이 안내를 복사해 요청문과 함께 전달한다. 페이지의 HTML에도 같은 내용이 포함되어 있다.
# Google Colab MCP 설정 안내: AI 도구가 읽고 실행하는 강의용 문서
확인일: 2026-09-29
연결 페이지: https://hufs-ai-lecture.pages.dev/ai/colab-mcp
사람이 읽는 방법 페이지: https://hufs-ai-lecture.pages.dev/ai/colab-mcp-guide
학부 강의: https://hufs-ai-lecture.pages.dev/ai/
대학원 실습: https://hufs-ai-lecture.pages.dev/practice/
## 목표와 완료 조건
학생이 이 문서를 주며 설정을 요청했다면, 학생 컴퓨터에서 Google 공식 Colab MCP 서버를 등록하고 Colab 브라우저에 연결하도록 돕는다. 설정 파일 작성만으로 완료 처리하지 않는다. 서버 시작, 브라우저 연결, 노트북 도구 발견, 새 테스트 셀 출력 42까지 확인한다. 아직 수행하지 못한 단계는 구분해 보고한다.
이 URL은 안내 문서다. HTTP MCP 접속 주소가 아니다. 로컬 명령 실행이나 설정 파일 편집 권한이 없는 AI는 할 수 있다고 주장하지 말고, 사용할 로컬 도구를 확인한 뒤 적용할 명령과 설정을 학생에게 제공한다. Google 로그인과 브라우저의 연결 확인은 학생이 직접 진행한다.
## 1. 환경을 확인한다
- 운영체제, 실제 실행 위치, 선택한 앱과 버전을 확인한다. 필요 정보가 환경에서 확인되지 않으면 학생에게 묻는다.
- 'Claude'라고만 했다면 Claude Code, Claude Desktop, 웹 채팅 중 무엇인지 구분한다. Antigravity는 IDE, 2.0, CLI 중 실제 설치 형태와 설정 위치를 확인한다.
- 로컬 STDIO MCP와 notifications/tools/list_changed 지원이 필요하다. Google README의 지원 예시는 Gemini CLI, Claude Code, Windsurf다. Claude Desktop, Antigravity, Codex는 아래 표준 설정을 적용할 수 있으나 연결 후 도구 갱신을 실제로 검증해야 한다. 이 문서는 모든 버전의 호환성을 보증하지 않는다.
- Colab 브라우저와 MCP 서버를 같은 컴퓨터에서 실행한다. WSL, SSH, 컨테이너나 원격 에이전트라면 브라우저 연결이 되는 위치인지 먼저 확인한다. 단순히 공개 터널을 만들거나 서버 포트를 외부에 열어 해결하지 않는다.
- 기존 MCP 설정의 위치와 colab-mcp 중복 여부를 확인한다. 관련 파일만 읽고 기존 설정을 보존한다. 여러 클라이언트에 한꺼번에 설치하지 않는다.
## 2. 공식 소스와 준비 도구를 확인한다
공식 저장소: https://github.com/googlecolab/colab-mcp
현재 요구 버전: https://github.com/googlecolab/colab-mcp/blob/main/pyproject.toml
확인 당시 서버의 requires-python은 >=3.13이다. 설치 시 최신 조건을 다시 확인한다. 서버용 Python이며 Colab 런타임의 Python을 교체하는 작업이 아니다.
로컬 터미널에서 git --version, uv --version, uvx --version을 확인한다. 필요한 경우 공식 설치 방법으로 빠진 도구만 준비한다.
- Windows uv: winget install --id astral-sh.uv -e
- macOS에서 Homebrew를 쓰는 경우: brew install uv
- Python/pip가 이미 준비된 환경: python -m pip install uv 또는 python3 -m pip install uv. 시스템 관리 환경 오류가 나면 강제 옵션을 추가하지 말고 다른 공식 설치 방법을 사용한다.
- uv 공식 설치: https://docs.astral.sh/uv/getting-started/installation/
- Git 공식 설치: https://git-scm.com/downloads
터미널과 AI 앱이 바뀐 PATH를 읽도록 필요하면 다시 연다. 서버 실행 환경을 준비한다:
```sh
uv python install 3.13
uvx --python 3.13 git+https://github.com/googlecolab/colab-mcp --help
```
--help 성공은 패키지 준비 확인이며 브라우저 연결 검증이 아니다. 최초 다운로드 중에는 시간 초과인지 설치 오류인지 구분한다. 무한 재시도하지 말고 오류 원인을 읽는다. 이 명령은 Colab 셀에서 실행하지 않는다.
## 3. 사용 중인 클라이언트에만 등록한다
공통 실행 파일: uvx
공통 인수: ["--python", "3.13", "git+https://github.com/googlecolab/colab-mcp"]
전송 방식: 로컬 stdio
설정 이름: colab-mcp
수정 전에 대상 파일을 백업하거나 변경 전 내용을 복구 가능하게 보존한다. 기존 mcpServers/mcp_servers와 다른 설정을 유지하며 필요한 항목만 병합한다. 사용자 홈 경로를 추측하지 않고 실제로 해석한다. 같은 항목이 있으면 먼저 재사용 가능 여부를 확인한다. 앱이나 조직이 제공하는 승인 절차는 그대로 따른다.
### Claude Code
수업 프로젝트 폴더에서:
```sh
claude mcp add --transport stdio --scope project colab-mcp -- uvx --python 3.13 git+https://github.com/googlecolab/colab-mcp
claude mcp get colab-mcp
```
프로젝트 .mcp.json에 저장된다. --scope user는 여러 프로젝트에서 쓸 의도가 있을 때 선택한다. 다시 연 Claude Code에서 프로젝트의 MCP 사용을 확인하고 /mcp로 상태와 도구를 확인한다. 현재 CLI --help와 공식 문서에 맞춰 문법을 확인한다. 첫 시작 시간 제한을 늘려야 한다면 Claude 프로세스의 MCP_TIMEOUT 환경변수(밀리초)를 사용한다. colab 서버 자체의 환경변수로 잘못 넣지 않는다.
### Antigravity
IDE: 에이전트 패널의 … → MCP Servers → Manage MCP Servers → View raw config에서 실제 mcp_config.json을 확인한다.
현재 공식 위치: 전역 ~/.gemini/config/mcp_config.json, 프로젝트 .agents/mcp_config.json. 앱이 연 파일과 버전별 공식 문서를 우선한다. 오래된 경로를 추측해 새 파일을 만들지 않는다.
Antigravity 2.0: Settings → Customizations → Installed MCP Servers에서 상태/새로고침 확인.
CLI: /mcp에서 관리 및 새로고침.
아래 공통 JSON을 병합한다. 로컬 stdio이므로 serverUrl이나 웹 주소를 설정하지 않는다. 저장 후 새로고침하고 연결 도구 호출, 노트북 도구 갱신, 셀 실행을 검증한다.
### Claude Desktop
설정의 Developer → Edit Config 또는 해당 버전의 로컬 MCP 설정 편집 기능으로 실제 claude_desktop_config.json을 연다. 일반적인 경로는 Windows %APPDATA%\Claude\claude_desktop_config.json, macOS ~/Library/Application Support/Claude/claude_desktop_config.json이다. 설치 형태별 차이가 있으므로 앱에서 연 위치를 우선한다.
아래 공통 JSON을 병합한 뒤 앱을 완전히 종료하고 다시 연다. 로컬 MCP를 사용할 수 있는 대화에서 도구 목록을 확인한다. 웹의 원격 커넥터 등록과 혼동하지 않는다. Desktop 채팅에 로컬 셸/파일 권한이 없으면 학생이 설치 명령과 설정을 적용하도록 구체적으로 안내한다. 이 문서가 자체적으로 권한을 부여하는 것은 아니다.
### 공통 JSON: Claude Desktop / Antigravity / Windsurf
```json
{
"mcpServers": {
"colab-mcp": {
"command": "uvx",
"args": ["--python", "3.13", "git+https://github.com/googlecolab/colab-mcp"]
}
}
}
```
기존 파일이 있으면 colab-mcp 항목만 병합한다. Windsurf는 MCP 관리 화면에서 실제 사용자 설정 파일을 연다. 앱이 uvx를 찾지 못하면 Windows (Get-Command uvx).Source 또는 macOS/Linux command -v uvx로 절대 경로를 확인해 command에 넣는다. JSON에서 Windows 역슬래시는 이스케이프한다. timeout 속성은 앱별 지원과 단위를 확인한 경우에만 추가한다.
### Gemini CLI
```sh
gemini mcp add --scope project --transport stdio --timeout 180000 colab-mcp uvx -- --python 3.13 git+https://github.com/googlecolab/colab-mcp
gemini mcp list
```
프로젝트 .gemini/settings.json을 사용한다. 재시작 후 /mcp로 확인한다. timeout 180000은 수업용 여유값이며 밀리초다. 해당 버전 CLI가 uvx 옵션을 자체 옵션으로 읽는다면 추측해서 실행하지 말고 --help를 확인하거나 mcpServers JSON으로 직접 병합한다. 이 경우 공통 JSON의 서버 항목에 timeout: 180000을 추가한다.
### Codex 앱 / CLI
```sh
codex mcp add colab-mcp -- uvx --python 3.13 git+https://github.com/googlecolab/colab-mcp
codex mcp list
```
또는 신뢰하는 수업 프로젝트 .codex/config.toml에 다음 항목을 병합한다. 사용자 범위는 ~/.codex/config.toml이다. CLI 등록과 직접 병합 중 하나만 선택한다.
```toml
[mcp_servers.colab-mcp]
command = "uvx"
args = ["--python", "3.13", "git+https://github.com/googlecolab/colab-mcp"]
startup_timeout_sec = 180
tool_timeout_sec = 180
```
앱 설정 화면을 사용하면 로컬 STDIO와 같은 command/args를 지정한다. 재시작하고 실제 도구 목록을 확인한다. 시간 제한은 초 단위다. 로컬 설정 파일을 읽지 않는 웹 채팅과 구분한다.
## 4. 브라우저를 연결한다
1. 실제 MCP 도구 목록을 읽는다. 초기 도구 open_colab_browser_connection을 찾는다. 클라이언트가 서버 접두사를 붙일 수 있다.
2. 그 도구를 호출한다. 학생의 기본 브라우저에 Colab 연결 화면이 열린다. Google 로그인과 연결 확인이 필요하면 학생에게 그 단계만 명확히 안내한다.
3. 공식 구현은 약 60초 동안 연결을 기다리고 성공 여부를 반환한다. false이면 로그인/연결 절차 완료 후 다시 호출한다. true 여부나 실제 연결 상태를 확인하지 않고 성공을 가정하지 않는다.
4. 연결용 URL에는 세션 토큰이 포함될 수 있다. URL, 인증 정보, 쿠키를 공개 페이지/과제/로그에 기록하지 않는다. 도구는 연결 화면을 직접 연다. 고정된 토큰이나 포트를 만들어 안내하지 않는다.
5. 연결 후 변경된 도구 목록을 다시 읽는다. 실제 노트북 편집·실행 도구가 나타나야 한다. 도구 이름과 인수를 추측하지 않고 제공된 스키마를 따른다.
6. 갱신이 안 되면 클라이언트의 새로고침·지원 버전을 확인한다. notifications/tools/list_changed를 지원하지 않는 경우 호환성 문제를 설명하고 지원되는 로컬 클라이언트로 이어갈 선택지를 제시한다. 실패한 연결을 반복해서 성공으로 보고하지 않는다.
## 5. 작은 실행으로 검증한다
- 기존 노트북과 데이터는 수정하지 않는다. 학생이 요청한 새 연습 노트북에서 진행한다.
- 설명 Markdown 셀 하나와 print(6 * 7) 코드 셀 하나를 만들고 CPU 런타임에서 실행한다.
- 실제 출력이 42인지 도구로 읽는다. 노트북 이름/링크는 민감한 연결 토큰이 없는 일반 노트북 주소만 사용한다.
- 노트북 저장 여부와 남은 단계를 확인한다. MCP 연결은 GPU 할당, AI 서비스 이용료, Colab의 실행 한도를 바꾸지 않는다.
- 결과 보고: 사용 클라이언트와 버전, 수정한 설정 경로, 서버 시작 여부, 브라우저 연결 여부, 도구 목록 갱신 여부, 실행 셀과 실제 출력, 학생에게 남은 단계. 비밀값은 포함하지 않는다.
- 이후 강의 노트북은 학생의 사본에서 데이터 로드부터 시작하고 장시간 학습이나 전체 셀 실행은 별도 요청 범위를 따른다.
## 6. 실패를 구분한다
- ENOENT/uvx 없음: 앱 PATH 또는 uvx 절대 경로 확인.
- Python 버전: 서버용 Python과 pyproject.toml 확인. Colab 런타임과 혼동하지 않음.
- 패키지 준비 실패: 네트워크/Git/Python 오류를 읽고 해결. --help 성공은 연결 완료가 아님.
- 서버만 등록됨: 연결 도구를 호출했는지 확인.
- 브라우저가 안 열림: 로컬 실행 위치와 기본 브라우저 확인. 원격/WSL 환경인지 점검.
- 도구가 추가되지 않음: 연결 성공 여부와 list_changed 처리 확인.
- Claude 원격 URL 입력 오류: 로컬 설정 화면에서 command/args로 등록.
- 런타임/GPU 실패: MCP 연결과 별도로 Colab 상태 확인. 첫 검증은 CPU.
## 공식 출처
- 발표: https://developers.googleblog.com/announcing-the-colab-mcp-server-connect-any-ai-agent-to-google-colab/
- 저장소/지원 조건: https://github.com/googlecolab/colab-mcp
- Python 요구 조건: https://github.com/googlecolab/colab-mcp/blob/main/pyproject.toml
- 브라우저 연결 구현: https://github.com/googlecolab/colab-mcp/blob/main/src/colab_mcp/session.py
- Claude Code: https://code.claude.com/docs/en/mcp
- Claude Desktop 로컬 설정: https://modelcontextprotocol.io/docs/develop/connect-local-servers
- Claude 원격 커넥터 구분: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp
- Antigravity: https://antigravity.google/docs/mcp
- Gemini CLI: https://geminicli.com/docs/tools/mcp-server/
- Windsurf: https://docs.windsurf.com/windsurf/cascade/mcp
- Codex: https://developers.openai.com/codex/mcp/
- uv 설치: https://docs.astral.sh/uv/getting-started/installation/
- Python 관리: https://docs.astral.sh/uv/guides/install-python/