Jupyter Notebook MCP Server
A FastMCP server that provides tools for interacting with Jupyter notebooks. Built using the FastMCP framework.
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:
{
"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:
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 filecell_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 filecell_content(str): Content of the new cellcell_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 filecell_index(int): Index of the cell to execute (0-based)kernel_name(str, default="python3"): Jupyter kernel to usetimeout(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 filekernel_name(str, default="python3"): Jupyter kernel to usetimeout_per_cell(int, default=30): Timeout per cell in secondsstop_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