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

Related MCP server: Jupyter MCP Server

🔧 설정

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 어시스턴트에서 가장 먼저 해야 할 일은 작업 공간을 초기화하는 것입니다. 이를 통해 서버에 프로젝트 파일과 노트북의 위치를 알릴 수 있습니다.

# Example tool call from the client (syntax may vary)
initialize_workspace(directory="/full/absolute/path/to/your/project_folder")

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

핵심 운영

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

# List notebooks
list_notebooks()

# Create a new notebook
create_notebook(filepath="analysis/new_analysis.ipynb", title="My New Analysis")

# Add a code cell to the notebook
add_cell(filepath="analysis/new_analysis.ipynb", content="import pandas as pd\ndf = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})\ndf.head()", cell_type="code")

# Read the first cell (index 0)
read_cell(filepath="analysis/new_analysis.ipynb", cell_index=0)

# Edit the second cell (index 1)
edit_cell(filepath="analysis/new_analysis.ipynb", cell_index=1, content="# This is updated markdown")

# Read the output of the second cell (index 1) after execution (if any)
read_cell_output(filepath="analysis/new_analysis.ipynb", cell_index=1)

# Read the entire notebook structure
read_notebook(filepath="analysis/new_analysis.ipynb")

🛠️ 사용 가능한 도구

🧪 개발 및 디버깅

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

• 직접 실행: 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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.