MCP Server Jupyter

🚀 mcp-server-jupyter Server

An MCP server for managing and interactively operating Jupyter notebooks, enabling programmatic management of notebooks.

✨ Features

Tools

This server provides six tools for notebook operations:

1. Read notebook content including output: Read notebook content, including cell outputs.

   • Required parameter: notebook_path (string)

2. Read only source code of the notebook: Read notebook content without outputs.

   • Suitable for cases where the full notebook cannot be read due to size limitations.
   • Required parameter: notebook_path (string)

3. Read output of a specific cell: Get the output content of a specified cell.

   • Required parameters:
     • notebook_path (string)
     • cell_id (string)

4. Add a new cell: Add a new cell to the notebook.

   • Required parameters:
     • notebook_path (string)
     • source (string)
   • Optional parameters:
     • cell_type (string): "code" or "markdown"
     • position (integer): Insertion position (-1 means append)

5. Edit cell content: Modify the content of a specified cell.

   • Required parameters:
     • notebook_path (string)
     • cell_id (string): Unique identifier
     • source (string)

6. Execute a specific cell: Execute a specified cell and return the output results.

   • Suitable for verifying cell execution and output.
   • Required parameters:
     • notebook_path (string)
     • cell_id (string)

📦 Installation

Step 1: Start JupyterLab or Jupyter Notebook

To facilitate virtual environment management and package installation, it is recommended to use uv to run Jupyter notebooks.

Refer to the uv's Jupyter documentation for more details:

uv venv --seed
source .venv/bin/activate
uv pip install jupyterlab
.venv/bin/jupyter lab

⚠️ Important Note

This environment should be used as the UV_PROJECT_ENVIRONMENT environment variable in the MCP server (next step). Make sure to run in the same directory.

echo $(pwd)/.venv

Step 2: Configure Claude Desktop

Add the following configuration to your Claude Desktop configuration file:

PyPi package installation method:

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "Jupyter-notebook-manager": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-jupyter", "mcp-server-jupyter"],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/path/to/venv_for_jupyter/.venv"
      }
    }
  }
}

Git repository cloning method:

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "Jupyter-notebook-manager": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/inna/mcp-server-jupyter/src/mcp_server_jupyter",
        "mcp-server-jupyter"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/path/to/venv_for_jupyter/.venv"
      }
    }
  }
}

Step 3: Usage Instructions

• Start a JupyterLab or Jupyter Notebook instance.
• When configuring the MCP server, ensure that the UV_PROJECT_ENVIRONMENT environment variable is set correctly.
• Add relevant dependencies to your project directory:

uv pip install mcp-server-jupyter

⚠️ Notes

• After modifying the notebook, please reload the page to apply the changes.
• Ensure that the Jupyter instance remains running to continue using the MCP server.

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for specific information.