python-notebook-mcp

This server allows compatible AI assistants (like Cursor or Claude Desktop) to interact with Jupyter Notebook files (.ipynb) on your local machine.

📋 Prerequisites

Before you begin, ensure you have the following installed:

1. Python: Version 3.10 or higher.

2. `uv`: The fast Python package installer and virtual environment manager from Astral. If you don't have it, install it:

# On macOS / Linux
    curl -LsSf https://astral.sh/uv/install.sh | sh

    # On Windows (PowerShell)
    powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

    # IMPORTANT: Add uv to your PATH if prompted by the installer
    # For macOS/Linux (bash/zsh), add to your ~/.zshrc or ~/.bashrc:
    # export PATH="$HOME/.local/bin:$PATH"
    # Then restart your shell or run `source ~/.zshrc` (or equivalent)

3. `fastmcp` CLI (Optional, for Claude Desktop `fastmcp install`): If you plan to use the `fastmcp install` method for Claude Desktop, you need the `fastmcp` command available.

# Using uv
    uv pip install fastmcp

    # Or using pipx (recommended for CLI tools)
    pipx install fastmcp

🔧 Setup

1. Clone the Repository:

git clone https://github.com/UsamaK98/python-notebook-mcp.git # Or your fork/local path
    cd python-notebook-mcp

2. Choose Setup Method:

Run the appropriate script for your OS from the project's root directory (where you just `cd`-ed into).

# Make script executable (if needed)
            chmod +x ./install_unix.sh
            # Run the script
            bash ./install_unix.sh

# You might need to adjust PowerShell execution policy first
            # Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
            .\install_windows.ps1

These scripts will create the `.venv`, install dependencies, and output the exact paths needed for your MCP client configuration.

Follow these steps if you prefer manual control or encounter issues with the scripts.

1. Create & Activate Virtual Environment:

# 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

*(You should see `(.venv)` or similar at the start of your shell prompt)*

2. Install Dependencies:

# Make sure your venv is active
            uv pip install -r requirements.txt

▶️ Running the Server

Make sure your virtual environment (`.venv`) is activated if you used manual setup.

Method 1: Direct Execution (Recommended for Cursor, General Use)

This method uses `uv run` to execute the server script directly using your current Python environment (which should now have the dependencies installed).

1. Run the Server:

# From the python-notebook-mcp directory
    uv run python server.py

The server will start and print status messages, including the (uninitialized) workspace directory.

2. Client Configuration (`mcp.json`): Configure your MCP client (e.g., Cursor) to connect. Create or edit the client's MCP configuration file (e.g., `.cursor/mcp.json` in your workspace).

Template (Recommended):

{
      "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
        }
      }
    }

> ❓ Why the full path to Python? GUI applications like Cursor might not inherit the same `PATH` environment as your terminal. Specifying the exact path to the Python interpreter inside your `.venv` ensures the server runs with the correct environment and dependencies.

> ⚠️ IMPORTANT: Replace the placeholder paths with the actual absolute paths on your system.

Method 2: Claude Desktop Integration (`fastmcp install`)

This method uses the `fastmcp` tool to create a dedicated, isolated environment for the server and register it with Claude Desktop. You generally don't need to activate the `.venv` manually for this method, as `fastmcp install` handles environment creation.

1. Install the Server for Claude:

# From the python-notebook-mcp directory
    fastmcp install server.py --name "Jupyter Notebook MCP"

📘 Usage

Key Concept: Workspace Initialization

Regardless of how you run the server, the first action you *must* take from your AI assistant is to initialize the workspace. This tells the server where your project files and notebooks are located.

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

> ⚠️ You must provide the full absolute path to the directory containing your notebooks. Relative paths or paths like `.` are not accepted. The server will confirm the path and list any existing notebooks found.

Core Operations

Once the workspace is initialized, you can use the available tools:

# 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")

🛠️ Available Tools

🧪 Development & Debugging

If you need to debug the server itself:

• Run Directly: Use `uv run python server.py` and observe the terminal output for errors or print statements.
• FastMCP Dev Mode: For interactive testing with the MCP Inspector:

# Make sure fastmcp is installed in your environment
    # uv pip install fastmcp
    uv run fastmcp dev server.py

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.