Python notebook mcp

이 서버를 사용하면 호환되는 AI 어시스턴트(예: Cursor 또는 Claude Desktop)가 로컬 컴퓨터의 Jupyter Notebook 파일(.ipynb)과 상호 작용할 수 있습니다.

📋 필수 조건

시작하기 전에 다음 사항이 설치되어 있는지 확인하세요.

1. Python: 버전 3.10 이상.
2. uv : Astral의 빠른 Python 패키지 설치 프로그램 및 가상 환경 관리자입니다. uv가 없다면 설치하세요.지엑스피1
3. fastmcp CLI(선택 사항, Claude Desktop fastmcp install 의 경우): Claude Desktop에 fastmcp install 방법을 사용하려면 fastmcp 명령을 사용할 수 있어야 합니다.
   # Using uv uv pip install fastmcp # Or using pipx (recommended for CLI tools) pipx install fastmcp

🔧 설정

1. 저장소 복제:
   git clone https://github.com/UsamaK98/python-notebook-mcp.git # Or your fork/local path cd python-notebook-mcp
2. 설치 방법을 선택하세요:
   • 옵션 A: 자동 설치(권장) 프로젝트의 루트 디렉토리(방금 cd -ed로 들어간 디렉토리)에서 OS에 적합한 스크립트를 실행합니다.
     • macOS / Linux:
       # Make script executable (if needed) chmod +x ./install_unix.sh # Run the script bash ./install_unix.sh
     • 윈도우(PowerShell):GXP5 이 스크립트는 .venv 생성하고, 종속성을 설치하고, MCP 클라이언트 구성에 필요한 정확한 경로를 출력합니다.
   • 옵션 B: 수동 설정 스크립트에 문제가 발생하거나 수동 제어를 선호하는 경우 다음 단계를 따르세요.
     1. 가상 환경 만들기 및 활성화:
        # Create the environment (e.g., named .venv) uv venv # Activate the environment # On macOS/Linux (bash/zsh): source .venv/bin/activate # On Windows (Command Prompt): # .venv\Scripts\activate.bat # On Windows (PowerShell): # .venv\Scripts\Activate.ps1
        (셸 프롬프트 시작 부분에 (.venv) 또는 이와 유사한 내용이 표시되어야 합니다.)
     2. 종속성 설치:
        # Make sure your venv is active uv pip install -r requirements.txt

▶️ 서버 실행

수동 설정을 사용한 경우 가상 환경( .venv )이 활성화되어 있는지 확인하세요.

방법 1: 직접 실행(커서, 일반 사용에 권장)

이 방법은 uv run 사용하여 현재 Python 환경(이제 종속성이 설치되었을 것임)을 사용하여 서버 스크립트를 직접 실행합니다.

1. 서버를 실행합니다:
   # From the python-notebook-mcp directory uv run python server.py
   서버가 시작되고 (초기화되지 않은) 작업 공간 디렉터리를 포함한 상태 메시지가 인쇄됩니다.
2. 클라이언트 구성( mcp.json ): MCP 클라이언트(예: Cursor)가 연결되도록 구성합니다. 클라이언트의 MCP 구성 파일(예: 작업 공간의 .cursor/mcp.json )을 생성하거나 편집합니다.템플릿(권장):
   { "mcpServers": { "jupyter": { // Use the absolute path to the Python executable inside your .venv "command": "/full/absolute/path/to/python-notebook-mcp/.venv/bin/python", // macOS/Linux // "command": "C:\\full\\absolute\\path\\to\\python-notebook-mcp\\.venv\\Scripts\\python.exe", // Windows "args": [ // Absolute path to the server script "/full/absolute/path/to/python-notebook-mcp/server.py" ], "autoApprove": ["initialize_workspace"] // Optional: Auto-approve certain safe tools } } }

   ❓ Python의 전체 경로를 사용하는 이유는 무엇인가요? Cursor와 같은 GUI 애플리케이션은 터미널과 동일한 PATH 환경을 상속하지 않을 수 있습니다. .venv 파일에 Python 인터프리터의 정확한 경로를 지정하면 서버가 올바른 환경 및 종속성으로 실행됩니다. ⚠️ 중요: 플레이스홀더 경로를 시스템의 실제 절대 경로 로 바꾸세요.

방법 2: Claude Desktop 통합( fastmcp install )

이 방법은 fastmcp 도구를 사용하여 서버 전용의 격리된 환경을 생성하고 Claude Desktop에 등록합니다. fastmcp install 이 환경 생성을 자동으로 처리하므로, 이 방법에서는 일반적으로 .venv 파일을 수동으로 활성화할 필요가 없습니다.

1. Claude를 위한 서버 설치:
   # From the python-notebook-mcp directory fastmcp install server.py --name "Jupyter Notebook MCP"
   • fastmcp install 백그라운드에서 uv 사용하여 환경을 만들고 requirements.txt 에서 종속성을 설치합니다.
   • 이제 서버가 Claude Desktop 개발자 설정에 나타나 활성화할 수 있습니다. fastmcp install 사용할 때는 일반적으로 claude_desktop_config.json 수동으로 편집할 필요가 없습니다 .

📘 사용법

핵심 개념: 작업 공간 초기화

서버를 어떻게 실행하든 AI 어시스턴트에서 가장 먼저 해야 할 일은 작업 공간을 초기화하는 것입니다. 이를 통해 서버에 프로젝트 파일과 노트북의 위치를 알릴 수 있습니다.

⚠️ 노트북이 있는 디렉터리의 전체 절대 경로를 제공 해야 합니다 . 상대 경로나 . 과 같은 경로는 허용되지 않습니다 . 서버에서 경로를 확인하고 기존 노트북이 있으면 나열합니다.

핵심 운영

작업 공간이 초기화되면 사용 가능한 도구를 사용할 수 있습니다.

🛠️ 사용 가능한 도구

🧪 개발 및 디버깅

서버 자체를 디버깅해야 하는 경우:

• 직접 실행: uv run python server.py 사용하고 오류나 출력 문이 있는지 터미널 출력을 관찰합니다.
• FastMCP 개발 모드: MCP 검사기를 사용한 대화형 테스트의 경우:
  # Make sure fastmcp is installed in your environment # uv pip install fastmcp uv run fastmcp dev server.py

📄 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.