mcp-server-jupyter
by: ihrpr
MCP server for Jupyter Notebooks and JupyterLab
📌Overview
Purpose: To provide an MCP server that enables programmatic management and interaction with Jupyter notebooks.
Overview: The mcp-server-jupyter facilitates the manipulation and execution of Jupyter notebooks through a set of defined tools. This framework streamlines workflows for developers and data scientists, enabling efficient notebook handling directly from a server.
Key Features:
-
Read Notebooks with Outputs: Allows users to retrieve entire notebook content, including cell outputs, which is vital for full notebook analysis.
-
Read Notebook Source Only: Provides a way to read the notebook's content without outputs to mitigate size issues, ensuring flexibility in handling large notebooks.
-
Cell Manipulation: Users can add new cells, edit existing ones, and execute specific cells to obtain outputs. This feature is crucial for iterative development and testing within notebooks.
-
Integration with Claude Desktop: Seamlessly integrates with Claude Desktop, allowing users to configure and run notebooks efficiently within their development environment.
mcp-server-jupyter
An MCP server for managing and interacting with Jupyter notebooks programmatically.
Components
Tools
The server provides six tools for notebook manipulation:
-
read_notebook_with_outputs
: Read a notebook's content including cell outputs- Required:
notebook_path
(string)
- Required:
-
read_notebook_source_only
: Read notebook content without outputs- Required:
notebook_path
(string) - Use when size limitations prevent reading full notebook with outputs
- Required:
-
read_output_of_cell
: Read output of a specific cell- Required:
notebook_path
(string)cell_id
(string)
- Required:
-
add_cell
: Add new cell to notebook- Required:
notebook_path
(string)source
(string)
- Optional:
cell_type
(string): "code" or "markdown"position
(integer): insertion index (-1 to append)
- Required:
-
edit_cell
: Modify existing cell content- Required:
notebook_path
(string)cell_id
(string)source
(string)
- Required:
-
execute_cell
: Execute a specific cell and return its output- Required:
notebook_path
(string)cell_id
(string)
- Required:
Usage with Claude Desktop
Step 1: Start JupyterLab or Jupyter Notebook
Using uv to run Jupyter notebooks makes it easier to manage virtual environments and package installations.
Follow uv jupyter documentation for details.
uv venv --seed
source .venv/bin/activate
uv pip install jupyterlab
.venv/bin/jupyter lab
Note: This environment should be used as UV_PROJECT_ENVIRONMENT
environment variable in MCP server. Run in the same folder where Jupyter is started.
echo $(pwd)/.venv
Step 2: Configure Claude Desktop
Add this configuration to your Claude Desktop config file:
PyPi package:
{
"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 repo fork:
{
"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: Open Notebook & Claude Chat
Open or create a notebook in JupyterLab or Jupyter Notebook.
Get the full path to your notebook:
- In JupyterLab: Right-click on the notebook in the file browser → Copy Path
- In Jupyter Notebook: Copy the path from the URL (modify to full system path)
In Claude Desktop chat:
- Always use the full path to the notebook when calling tools.
- Example:
/Users/username/projects/my_notebook.ipynb
Important Notes:
- After any modifications through Claude (add_cell, edit_cell), reload the notebook page in JupyterLab/Jupyter Notebook because the current version does not support automatic reload.
- Keep the JupyterLab/Jupyter Notebook instance running while working with Claude.
License
This project is licensed under the MIT License. See the LICENSE file for details.