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:

Python: Version 3.10 or higher.
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)
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

Clone the Repository:
git clone https://github.com/UsamaK98/python-notebook-mcp.git # Or your fork/local path cd python-notebook-mcp
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:
    # Make script executable (if needed) chmod +x ./install_unix.sh # Run the script bash ./install_unix.sh
  - Windows (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:
    # 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).

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

Install the Server for Claude:
# 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.

# 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

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