iflow-mcp_python-notebook-mcp 0.1.0
Lightweight Python Notebook MCP - Enable AI assistants to create, edit, and view Jupyter notebooks via Model Context Protocol
License: MIT
Requires Python: >=3.10

<div align="center">
  <h1>Python Notebook MCP</h1>
  <p>MCP server enabling AI assistants to interact with Jupyter notebooks through the Model Context Protocol.</p>
  <p>
    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"/></a>
    <img src="https://img.shields.io/badge/Python-3.10+-blue.svg" alt="Python 3.10+"/>
    <img src="https://img.shields.io/badge/MCP-Compatible-orange.svg" alt="MCP Compatible"/>
    <a href="https://mseep.ai/app/286d0c4c-dcec-477b-bc2c-b20d2ce85ef2"><img src="https://mseep.ai/badge.svg" alt="Verified on MseeP"/></a>
    <a href="CodeRabbit Pull Request Reviews"><img src="https://img.shields.io/coderabbit/prs/github/UsamaK98/python-notebook-mcp?utm_source=oss&utm_medium=github&utm_campaign=UsamaK98%2Fpython-notebook-mcp&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews"/>
  </p>
</div>
<div align="center">
<a href="https://mseep.ai/app/usamak98-python-notebook-mcp"><img src="https://mseep.net/pr/usamak98-python-notebook-mcp-badge.png" alt="MseeP.ai Security Assessment Badge"/></a> 
</div>
 
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:
    ```bash
    # 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.
    ```bash
    # Using uv
    uv pip install fastmcp

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

## 🔧 Setup

1.  **Clone the Repository:**
    ```bash
    git clone https://github.com/UsamaK98/python-notebook-mcp.git # Or your fork/local path
    cd python-notebook-mcp
    ```

2.  **Choose Setup Method:**

    *   **Option A: Automated Setup (Recommended)**
        Run the appropriate script for your OS from the project's root directory (where you just `cd`-ed into).
        *   **macOS / Linux:**
            ```bash
            # Make script executable (if needed)
            chmod +x ./install_unix.sh
            # Run the script
            bash ./install_unix.sh
            ```
        *   **Windows (PowerShell):**
            ```powershell
            # 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.

    *   **Option B: Manual Setup**
        Follow these steps if you prefer manual control or encounter issues with the scripts.
        1.  **Create & Activate Virtual Environment:**
            ```bash
            # 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:**
            ```bash
            # 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:**
    ```bash
    # 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):**
    ```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
        }
      }
    }
    ```
    > **❓ 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:**
    ```bash
    # From the python-notebook-mcp directory
    fastmcp install server.py --name "Jupyter Notebook MCP"
    ```
    *   `fastmcp install` uses `uv` behind the scenes to create the environment and install dependencies from `requirements.txt`.
    *   The server will now appear in the Claude Desktop developer settings and can be enabled there. You generally *don't* need to manually edit `claude_desktop_config.json` when using `fastmcp install`.

## 📘 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.

```python
# 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:

```python
# 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

| Tool                     | Description                                                        |
| :----------------------- | :----------------------------------------------------------------- |
| `initialize_workspace`   | **REQUIRED FIRST STEP.** Sets the absolute path for the workspace. |
| `list_notebooks`         | Lists all `.ipynb` files found within the workspace directory.     |
| `create_notebook`        | Creates a new, empty Jupyter notebook if it doesn't exist.       |
| `read_notebook`          | Reads the entire structure and content of a notebook.              |
| `read_cell`              | Reads the content and metadata of a specific cell by index.        |
| `edit_cell`              | Modifies the source content of an existing cell by index.          |
| `add_cell`               | Adds a new code or markdown cell at a specific index or the end. |
| `read_notebook_outputs`  | Reads all outputs from all code cells in a notebook.               |
| `read_cell_output`       | Reads the output(s) of a specific code cell by index.              |

## 🧪 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:
    ```bash
    # 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](LICENSE) file for details.