NotebookLLM MCP Server

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

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.