mcp-server-jupyter
# mcp-server-jupyter
An MCP server for managing and interacting with Jupyter notebooks programmatically.
## Components
### Tools
The server provides six tools for notebook manipulation:
1. `read_notebook_with_outputs`: Read a notebook's content including cell outputs
- Required: `notebook_path` (string)
2. `read_notebook_source_only`: Read notebook content without outputs
- Required: `notebook_path` (string)
- Use when size limitations prevent reading full notebook with outputs
3. `read_output_of_cell`: Read output of a specific cell
- Required:
- `notebook_path` (string)
- `cell_id` (string)
4. `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)
5. `edit_cell`: Modify existing cell content
- Required:
- `notebook_path` (string)
- `cell_id` (string): Unique ID of the cell to edit
- `source` (string)
6. `execute_cell`: Execute a specific cell and return its output
- Required:
- `notebook_path` (string)
- `cell_id` (string)
- Useful for verifying cell execution and output
## Usage with Claude Desktop
### Step1: Start JupyterLab or Jupyter Notebook
By using uv to run Jupyter notebooks it's much easier to manage venv and package installations.
Follow [uv jupyter docummentation](https://docs.astral.sh/uv/guides/integration/jupyter/) for more details.
```bash
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` env variable in MCP server (next step). Run in the same folder where Jupyter started.
```
echo $(pwd)/.venv
```
### Step2: Configure Claude Desctop Add this configuration to your Claude Desktop config file:
**PyPi package:**
```json
// ~/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 repo fork**
```json
// ~/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: Open Notebook & Claude Chat
Open or create a notebook in JupyterLab/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
- Current version does not support automatic reload
- Keep JupyterLab/Jupyter Notebook instance running while working with Claude
## License
This project is licensed under the MIT License. See the LICENSE file for details.
TDQS
Scored across 6 tools
Each tool targets a distinct operation: reading the full notebook with or without outputs, reading a specific cell's output, executing a cell, adding a cell, and editing a cell. The two read-notebook variants are clearly differentiated by their descriptions and use cases, so there is no real ambiguity.
All tool names follow a consistent snake_case verb_noun pattern (e.g., read_notebook_with_outputs, execute_cell, add_cell). The three read_* variants are slightly longer but still adhere to the same convention, and the overall style is uniform.
With six tools, the server is well-scoped for the purpose of reading, executing, and modifying Jupyter notebooks. The number is neither too thin nor excessive, and each tool covers a distinct aspect of the core workflow.
The tool surface covers the primary notebook operations: reading (with/without outputs, specific cell output), executing cells, adding cells, and editing cells. A notable gap is the absence of a delete_cell tool, but this does not critically hinder common workflows and can be worked around by editing cell content.