Skip to main content
Glama

Python notebook mcp

by UsamaK98
README.md9.9 kB
<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.

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/UsamaK98/python-notebook-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server