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