python-notebook-mcp

Overview

Python Notebook MCP is a lightweight server that enables AI assistants like Cursor and Claude Desktop to interact with Jupyter notebooks through the Model Context Protocol. It allows initializing a workspace and then performing various operations on notebook files including creating, reading, editing cells, and accessing cell outputs. The server is well-documented with clear setup instructions for different operating systems and multiple installation methods.

Try asking AI

After installing, here are 5 things you can ask your AI assistant:

• initialize_workspaceinitialize_workspace(directory: str)

  Sets the absolute path for the workspace directory.

  Try:Initialize workspace with the current directoryTry:Set workspace to /home/user/projects
• list_notebookslist_notebooks()

  Lists all .ipynb files found within the workspace directory.

  Try:Show me all notebooks in the workspaceTry:List available Jupyter notebooks
• create_notebookcreate_notebook(filepath: str, title: str)

  Creates a new, empty Jupyter notebook if it doesn't exist.

  Try:Create a new notebook called analysis.ipynbTry:Make a new notebook in the data folder
• read_notebookread_notebook(filepath: str)

  Reads the entire structure and content of a notebook.

  Try:Read contents of my_notebook.ipynbTry:Show me the structure of analysis.ipynb
• read_cellread_cell(filepath: str, cell_index: int)

  Reads the content and metadata of a specific cell by index.

  Try:Show me cell 0 in my_notebook.ipynbTry:Read the content of the third cell
• edit_celledit_cell(filepath: str, cell_index: int, content: str)

  Modifies the source content of an existing cell by index.

  Try:Update cell 1 with new codeTry:Change cell 2 to contain markdown text
• add_celladd_cell(filepath: str, content: str, cell_type: str, index: int = null)

  Adds a new code or markdown cell at a specific index or at the end.

  Try:Add a new code cell to my_notebook.ipynbTry:Insert a markdown cell at the beginning
• read_notebook_outputsread_notebook_outputs(filepath: str)

  Reads all outputs from all code cells in a notebook.

  Try:Show me all outputs from my_notebook.ipynbTry:Display results from all code cells
• read_cell_outputread_cell_output(filepath: str, cell_index: int)

  Reads the output(s) of a specific code cell by index.

  Try:Show the output of cell 5 in analysis.ipynbTry:What did cell 3 produce when run?

Comparable tools

Installation

git clone https://github.com/UsamaK98/python-notebook-mcp.git
cd python-notebook-mcp

uv venv
source .venv/bin/activate  # or .venv\Scripts\activate.bat on Windows

uv pip install -r requirements.txt

{
  "mcpServers": {
    "jupyter": {
      "command": "/full/path/to/.venv/bin/python",
      "args": ["/full/path/to/server.py"]
    }
  }
}

fastmcp install server.py --name "Jupyter Notebook MCP"

FAQ

What's the first step I need to take after connecting to the server?

You must initialize the workspace using the initialize_workspace tool with the absolute path to your project directory containing notebooks.

Can I use relative paths for notebook files?

No, the server requires absolute paths for all notebook operations. Relative paths like '.' are not accepted.

Compare python-notebook-mcp with