UsamaK98/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.
## 📋 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