# Jupyter Notebook MCP Server

A FastMCP server that provides tools for interacting with Jupyter notebooks. Built using the [FastMCP framework](https://github.com/jlowin/fastmcp).


## Features

- ✅ Read notebook cells with filtering
- ✅ Add new cells at any position
- ✅ Execute individual cells
- ✅ Execute entire notebooks
- ✅ Get notebook metadata and statistics
- ✅ Proper error handling and validation
- ✅ Progress reporting for long operations
- ✅ Comprehensive logging via FastMCP Context

## Integration with your MCP Client

Make sure uv is installed.
To use this server with cursor, claude desktop or any other MCP client, add the following to your mcp config file:

```json
{
  "mcpServers": {
    "jupyter-notebook": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp>=2.8.1",
        "python",
        "<absolute_path_to_jupyter_mcp_server>/main.py"
      ]
    }
  }
}
```

### Testing

Run the test client to see all functionality in action:

```bash
python test_client.py
```

## Security Notes

- Cell execution runs Python code directly via subprocess
- Only execute notebooks from trusted sources
- Consider running in a sandboxed environment for production use
- Timeout controls help prevent runaway executions

## Dependencies

- `fastmcp` - MCP server framework

## Tools

This MCP server provides the following tools for working with Jupyter notebooks:

### 📖 `read_notebook_cells`
Read cells from a Jupyter notebook with optional filtering by cell type.

**Parameters:**
- `notebook_path` (str): Path to the .ipynb file
- `cell_type` (optional str): Filter by cell type ('code', 'markdown', 'raw')

### ➕ `add_cell_to_notebook`
Add a new cell to a Jupyter notebook at a specified position.

**Parameters:**
- `notebook_path` (str): Path to the .ipynb file
- `cell_content` (str): Content of the new cell
- `cell_type` (str, default="code"): Type of cell ('code', 'markdown', 'raw')
- `position` (optional int): Position to insert cell (default: append to end)
- `metadata` (optional dict): Optional cell metadata

### ⚡ `execute_notebook_cell`
Execute a specific cell in a Jupyter notebook.

**Parameters:**
- `notebook_path` (str): Path to the .ipynb file
- `cell_index` (int): Index of the cell to execute (0-based)
- `kernel_name` (str, default="python3"): Jupyter kernel to use
- `timeout` (int, default=30): Execution timeout in seconds

### 🔄 `execute_entire_notebook`
Execute all code cells in a Jupyter notebook sequentially.

**Parameters:**
- `notebook_path` (str): Path to the .ipynb file
- `kernel_name` (str, default="python3"): Jupyter kernel to use
- `timeout_per_cell` (int, default=30): Timeout per cell in seconds
- `stop_on_error` (bool, default=True): Whether to stop execution if a cell fails

### 📊 `get_notebook_info`
Get basic information about a Jupyter notebook.

**Parameters:**
- `notebook_path` (str): Path to the .ipynb file