Notebookllm

PyPI Downloads A Model Context Protocol server for working with Jupyter Notebooks (.ipynb files) in a way that is efficient for Large Language Models (LLMs). It converts notebooks to a simplified plain text format to reduce token usage and cost, and can convert them back.

Available Tools

• load_notebook: Loads a .ipynb file into memory.
  • Arguments:
    • filepath (string): The absolute path to the .ipynb file.
  • Returns: (string) Success or failure message, including cell count.
• notebook_to_plain_text: Converts a .ipynb file (loaded or from path) to a simplified plain text representation.
  • Arguments:
    • input_filepath (string, optional): Absolute path to the .ipynb file for on-the-fly conversion.
  • Returns: (string) Plain text representation or error message.
• plain_text_to_notebook_file: Converts plain text content back to a .ipynb file and saves it.
  • Arguments:
    • plain_text_content (string): Plain text content to convert.
    • output_filepath (string): Absolute path to save the .ipynb file (must end with .ipynb).
  • Returns: (string) Success or failure message.
• add_code_cell_to_loaded_notebook: Adds a new code cell to the currently loaded notebook.
  • Arguments:
    • code_content (string): Source code for the new cell.
    • position (integer, optional): Position to insert the cell (appends if null).
  • Returns: (string) Success or failure message and current cell count.
• add_markdown_cell_to_loaded_notebook: Adds a new markdown cell to the currently loaded notebook.
  • Arguments:
    • markdown_content (string): Markdown content for the new cell.
    • position (integer, optional): Position to insert the cell (appends if null).
  • Returns: (string) Success or failure message and current cell count.
• save_loaded_notebook: Saves the currently loaded notebook to a file.
  • Arguments:
    • output_filepath (string, optional): Absolute path to save the .ipynb file (must end with .ipynb). Saves to original path if null.
  • Returns: (string) Success or failure message.

Installation

Using uv (recommended)

When using uv, no specific installation is needed. We will use uvx to directly run notebookllm_mcp.

Using PIP

Alternatively, you can install notebookllm_mcp via pip:

pip install notebookllm-mcp

After installation, you can run it as a script using:

python -m notebookllm_mcp

Configuration

Configure for Claude.app

Add to your Claude settings:

Using uvx

{
  "mcpServers": {
    "notebookllm": {
      "command": "uvx",
      "args": ["notebookllm_mcp"]
    }
  }
}

Using pip installation

{
  "mcpServers": {
    "notebookllm": {
      "command": "python",
      "args": ["-m", "notebookllm_mcp"]
    }
  }
}

Configure for Zed

Add to your Zed settings.json:

Using uvx

"context_servers": [
  "notebookllm": {
    "command": "uvx",
    "args": ["notebookllm_mcp"]
  }
],

Using pip installation

"context_servers": {
  "notebookllm": {
    "command": "python",
    "args": ["-m", "notebookllm_mcp"]
  }
},

Configure for VS Code

For quick installation, use one of the one-click install buttons below...

Install with UV in VS Code Install with UV in VS Code Insiders

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P (or Cmd + Shift + P on macOS) and typing Preferences: Open User Settings (JSON).

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

Note that the mcp key is needed when using the mcp.json file.

Using uvx

{
  "mcp": {
    "servers": {
      "notebookllm": {
        "command": "uvx",
        "args": ["notebookllm_mcp"]
      }
    }
  }
}

Using pip installation

{
  "mcp": {
    "servers": {
      "notebookllm": {
        "command": "python",
        "args": ["-m", "notebookllm_mcp"]
      }
    }
  }
}

Example Interactions

1. Load a notebook:

   {
     "name": "load_notebook",
     "arguments": {
       "filepath": "/path/to/your/notebook.ipynb"
     }
   }
   

   Response:

   {
     "message": "Notebook /path/to/your/notebook.ipynb loaded successfully. Cell count: 10"
   }
   

2. Convert loaded notebook to plain text:

   {
     "name": "notebook_to_plain_text",
     "arguments": {}
   }
   

   Response:

   # CELL 1 CODE
   print("Hello World")
   
   # CELL 2 MARKDOWN
   This is a markdown cell.
   ...
   

3. Convert plain text back to a notebook file:

   {
     "name": "plain_text_to_notebook_file",
     "arguments": {
       "plain_text_content": "# CELL 1 CODE\nprint(\"Hello Again\")\n\n# CELL 2 MARKDOWN\nAnother markdown cell.",
       "output_filepath": "/path/to/your/new_notebook.ipynb"
     }
   }
   

   Response:

   {
     "message": "Notebook saved to /path/to/your/new_notebook.ipynb"
   }
   

Debugging

You can use the MCP inspector to debug the server. For uvx installations:

npx @modelcontextprotocol/inspector uvx notebookllm_mcp

Or if you've installed the package via pip:

npx @modelcontextprotocol/inspector python -m notebookllm_mcp

Build

This package is typically installed via pip or used directly with uvx. If you are developing the package, you can build it using standard Python build tools.

python -m build

Contributing

Contributions are welcome! Please feel free to submit pull requests for bug fixes, new features, or improvements to documentation.

License

This project is licensed under the MIT License.