Jupyter VS Code MCP

Jupyter 노트북 작업을 일반 HTTP를 통한 MCP 도구로 노출하는 VS Code 확장 — 모든 AI 코딩 에이전트를 위한 하나의 포터블 URL. 절대 경로도, node 명령도, stdio 연결 설정도 필요 없습니다.

URL에 아무 MCP 클라이언트나 지정하면 에이전트가 활성 편집기 세션에서 노트북을 탐색, 편집, 실행, 디버그할 수 있습니다: 에이전트는 사용자가 보는 것과 동일한 셀을 보고, 노트북이 사용하는 동일한 커널(로컬 또는 원격 — Colab 포함)과 통신하며, 모든 작업은 실제 VS Code UI에 반영됩니다.

기능

안정적인 셀 핸들을 통한 노트북 편집

• 모든 셀은 단일 통일 방식인 #NB-xxxxxxxx로 식별되며, 표준 nbformat 4.5 셀 id 필드에 저장됩니다. 다른 셀의 편집, 삽입/삭제, 인덱스 이동, 저장/다시 열기, 확장 프로그램 리로드 — 심지어 파일을 다른 머신으로 복사하는 경우에도 유지됩니다.

• 삭제 후 ID가 재사용되는 일은 없습니다: 새 셀은 항상 새로운 무작위 ID를 받습니다. jupyter_get_summary는 ID가 없는 셀(예: UI에서 직접 만든 셀)에 ID를 할당하므로 보고된 모든 핸들을 즉시 재사용할 수 있습니다.

• 인덱스는 모든 곳에서 0부터 시작합니다(요약, 소스, 실행 범위, 출력) — 혼합 규칙이 없습니다.

비차단 실행 제어

• jupyter_run_cells는 실행을 시작하고 즉시 반환합니다. jupyter_wait_until_idle로 폴링하거나 jupyter_get_status로 스냅샷을 찍으세요. 맹목적인 sleep 없음, 긴 셀에서의 MCP 타임아웃 없음.

• 커널 준비 상태 가드: 죽었거나 없는 커널을 대상으로 실행하면 멈춰버리는 대신 실행 가능한 힌트를 반환합니다.

• jupyter_interrupt_kernel은 모든 변수를 유지하면서 현재 실행을 중단합니다.

커널 인텔리전스(Copilot급)

• jupyter_get_variables — 타입 인식 변수 보고서: DataFrame/Series는 {shape, columns[:8], head(2)}, ndarray는 {shape, dtype}, 컨테이너는 length, 스칼라는 짧은 repr로 표시합니다. 가능하면 공식 Jupyter 변수 보기 API를 사용하고, 그렇지 않으면 실행 횟수에 영향을 주지 않는 무음 커널 프로브를 사용합니다. 선택적 문서 심볼 필터링은 심볼을 실제로 사용할 수 있을 때만 내부 노이즈를 숨깁니다.

• jupyter_get_pip_packages — 활성 커널 환경의 환경 인벤토리(이름 + 버전).

• jupyter_install_packages — pip는 커널 자체 인터프리터 내부에서 실행되므로 패키지는 노트북이 실제로 사용하는 런타임에 설치됩니다 — Colab 같은 원격 VM도 포함되며, 로컬 호스트에는 절대 설치되지 않습니다. 버전 지정과 --upgrade를 지원하고, 이후 각 지정이 실제로 해결되는지 검증하며, 성공한 척하지 않고 실제 실패(pip의 실제 출력 끝부분 포함)를 정직하게 보고합니다.

• jupyter_get_status는 오래된 메타데이터를 신뢰하지 않고 활성 커널에서 실제 Python 버전/플랫폼을 조회합니다.

• jupyter_select_kernel은 활성 커널이 없을 때 VS Code의 기본 커널 선택기를 엽니다.

네트워크 전용 MCP 전송

• Streamable HTTP(MCP 스펙 2025-11-25)와 일반 JSON 응답 — 최소 클라이언트는 curl만으로 동작합니다.

• 엔드포인트: /mcp(레거시 /sse 포함), 활성 상태 + 버전 탐지를 위한 GET /health.

• 여러 동시 에이전트 세션 지원; 세션은 핫 포트 변경에도 유지됩니다.

정직한 보고

오류에는 맥락과 다음 단계 힌트가 포함됩니다: 커널 없음 → 부팅 안내, 오래된 ID → 요약을 통한 새로고침, pip 설치 실패 → 실제 pip 오류 끝부분, 바쁜 커널 → 조용히 빈 결과를 반환하는 대신 명시적 지연 안내.

Related MCP server: Jupyter MCP Server

도구

안정적인 ID

모든 은 표준 nbformat 4.5 id 필드에 기록되는 무작위 영구 ID(#NB-xxxxxxxx)를 받습니다 — 플폿폼 자체가 읽고 저장/로드를 통해 왕복하는 바로 그 슬롯입니다. ID는 위치 변겅, 콘텐츠 편집, 형제 삽입/삭제, 다시 열기 주기에 영햡을 받지 않습니다. 인덱스보다 ID를 선호하세요. jupyter_get_summary를 호출해 ID를 확핝할 수 있습니다(도구 외부에성 생된 에 누락된 ID를 백필하기도 합니다).

접두사 없는 8자리 16진수 입렵(abcd1234)은 #NB-abcd1234의 약식으러 허용됩니다.

호환 에이전트

HTTP를 사용하는 모든 MCP 클라이언트가 작동합니다. 일반적인 구성:

Claude Code, Cursor, Windsurf, Cine, Copilot:

{
  "mcpServers": {
    "jupyter-vscode-mcp": {
      "url": "http://localhost:9123/mcp"
    }
  }
}

OpenCode, Kilo Code:

{
  "mcp": {
    "jupyter-vscode-mcp": {
      "type": "remote",
      "url": "http://localhost:9123/mcp",
      "enabled": true
    }
  }
}

명령 팔레트에서 **"Jupyter VS Code MCP: Show MCP Configuration"**을 실행 → 에이전트 선텍 → 스니펫이 클립보드에 복사됩니다.

설피 및 실행

최신 .vsix를 Releases에서 다운로드한 후:

code --install-extension jupyter-vscode-mcp-<version>.vsix

1. 아무 .ipynb나 엽니다 — 서버가 127..0.1:9123에서 자동 시작됩니다(상태 표시줄에 상태가 표시되며, 클릭하여 전환).

2. 위의 URL 구성을 에이전트에 추가합니다.

3. 언제든 활성 상태를 확인하세요: curl http://localhost:9123/health.

설정: jupyter-vscode-mcp.mcpPort(기본값 9123, 즉시 적용), jupyter-vscode-mcp.autoStart(기본값 true).

권장 워크플로우

jupyter_list_open_notebooks   → pick notebook
jupyter_get_summary           → stable #NB-* IDs, exec state        (0-based)
jupyter_get_cell_source       → read only what you need
jupyter_edit_cell             → IDs stay valid after edits
jupyter_run_cells             → starts async, returns immediately
jupyter_wait_until_idle       → blocks until done (or poll get_status)
jupyter_get_outputs           → inline short text, artifact files for big/binary
jupyter_get_variables         → inspect kernel state after runs

아키텤처

AI agent ──HTTP/JSON-RPC──▶ VS Code extension (in-process http server :9123)
                                 │ vscode.* APIs + ms-toolsai.jupyter public API
                                 ▼
                     notebook cells, outputs, kernel status

커널 상호작용은 문서화된 ms-toolsai.jupyter 공개 API(kernel.executeCode, 인터럽트/재시작 명령, 변수/pip 목록 명령)를 명령 폴백과 함께 사용합니다. 실헹 추적은 workspace.onDidChangeNotebookDocument에 의존합니다.

개발

npm install
npm run compile      # typecheck
npm run lint
npm run build        # esbuild bundle
npm run smoke        # local protocol smoke test (vscode stubbed)
npx @vscode/vsce package

참고 자료

• Model Context Protocol — Streamable HTTP 전송, 스펙 2025-11-25

• microsoft/vscode-copilot-chat (MIT) — 변수 요약, 잘림 예산, 심볼 필터링 패턴

• SMARK OpenCode IDE Bridge — Jupyter 공개 API를 통한 커널 사전 검사, 인터럽트/재시작 명령 폴백, 이벤트 기반 완료 추적

• kriss-spy/opencode-jupyter — 원래 HTTP 브리지 개념

라이선스

MIT