Python Notebook MCP

MCP server enabling AI assistants to interact with Jupyter notebooks through the Model Context Protocol.

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

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)

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

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

-

Option A: Automated Setup (Recommended)Run the appropriate script for your OS from the project's root directory (where you justcd-ed into).

- macOS / Linux:

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

Option B: Manual SetupFollow these steps if you prefer manual control or encounter issues with the scripts.
- 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

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

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

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

This method usesuv runto execute the server script directly using your current Python environment (which should now have the dependencies installed).

# 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.jsonin your workspace).

{ "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 samePATHenvironment as your terminal. Specifying the exact path to the Python interpreter inside your.venvensures the server runs with the correct environment and dependencies.⚠️ IMPORTANT:Replace the placeholder paths with the actualabsolute pathson your system.

Method 2: Claude Desktop Integration (fastmcp install)

This method uses thefastmcptool to create a dedicated, isolated environment for the server and register it with Claude Desktop. You generally don't need to activate the.venvmanually for this method, asfastmcp installhandles environment creation.
- Install the Server for Claude:

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

- fastmcp installusesuvbehind the scenes to create the environment and install dependencies fromrequirements.txt.
- The server will now appear in the Claude Desktop developer settings and can be enabled there. You generallydon'tneed to manually editclaude_desktop_config.jsonwhen usingfastmcp install.

Regardless of how you run the server, thefirst actionyoumusttake 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")

⚠️ Youmustprovide the fullabsolute pathto 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.

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

- Run Directly:Useuv run python server.pyand 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

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

Set up and interact with your unstructured data processing workflows in Unstructured Platform