Skip to content
Back to search

jupyter-notebook-mcp

A Model Context Protocol (MCP) for Jupyter Notebook

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jjsantos01--jupyter-notebook-mcp/badge.svg)](/listings/jjsantos01--jupyter-notebook-mcp)

HTML

<a href="/listings/jjsantos01--jupyter-notebook-mcp"><img src="/api/listings/jjsantos01--jupyter-notebook-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Prerequisites

- [Python 3.12 or newer](https://www.python.org/downloads/) (probably also work with older versions, but not tested) - [`uv` package manager](/README.md#installing-uv) - [Claude AI desktop application](https://claude.ai/download)

Installing uv

If you're on Mac:

brew install uv

On Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

For other platforms, see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).

Setup

1. Clone or download this repository to your computer:

   git clone https://github.com/jjsantos01/jupyter-notebook-mcp.git

2. Create virtual environment with required packages an install `jupyter-mcp` kernel, so it can be recognized by your jupyter installation, if you had one before.

   uv run python -m ipykernel install --name jupyter-mcp

3. (optional) Install additional Python packages for your analysis:

   uv pip install seaborn

4. Configure Claude desktop integration: Go to `Claude` > `Settings` > `Developer` > `Edit Config` > `claude_desktop_config.json` to include the following:

      {
       "mcpServers": {
           "jupyter": {
               "command": "uv",
               "args": [
                   "--directory",
                   "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/src",
                   "run",
                   "jupyter_mcp_server.py"
               ]
           }
       }
   }

Replace `/ABSOLUTE/PATH/TO/` with the actual path to the `src` folder on your system. For example: - Windows: `"C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"` - Mac: `/Users/MyUser/GitHub/jupyter-notebook-mcp/src/`

If you had previously opened Claude, then `File` > `Exit` and open it again.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 306 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # JupyterMCP - Jupyter Notebook Model Context Protocol Integration
  2. JupyterMCP connects [Jupyter Notebook](https://jupyter.org/) to [Claude AI](https://claude.ai/chat) through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Jupyter Notebooks. This integration enables AI-assisted code execution, data analysis, visualization, and more.
  3. ## ⚠️ Compatibility Warning
  4. **This tool is compatible ONLY with Jupyter Notebook version 6.x.**
  5. It does NOT work with:
  6. - Jupyter Lab
  7. - Jupyter Notebook v7.x
  8. - VS Code Notebooks
  9. - Google Colab
  10. - Any other notebook interfaces
  11. ## Features
  12. - **Two-way communication**: Connect Claude AI to Jupyter Notebook through a WebSocket-based server
  13. - **Cell manipulation**: Insert, execute, and manage notebook cells
  14. - **Notebook management**: Save notebooks and retrieve notebook information
  15. - **Cell execution**: Run specific cells or execute all cells in a notebook
  16. - **Output retrieval**: Get output content from executed cells with text limitation options
  17. ## Components
  18. The system consists of three main components:
  19. 1. **WebSocket Server (`jupyter_ws_server.py`)**: Sets up a WebSocket server inside Jupyter that bridges communication between notebook and external clients
  20. 2. **Client JavaScript (`client.js`)**: Runs in the notebook to handle operations (inserting cells, executing code, etc.)
  21. 3. **MCP Server (`jupyter_mcp_server.py`)**: Implements the Model Context Protocol and connects to the WebSocket server
  22. ## Installation
  23. ### Prerequisites
  24. - [Python 3.12 or newer](https://www.python.org/downloads/) (probably also work with older versions, but not tested)
  25. - [`uv` package manager](/README.md#installing-uv)
  26. - [Claude AI desktop application](https://claude.ai/download)
  27. #### Installing uv
  28. If you're on Mac:
  29. ```bash
  30. brew install uv
  31. ```
  32. On Windows (PowerShell):
  33. ```bash
  34. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  35. ```
  36. For other platforms, see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
  37. ### Setup
  38. 1. Clone or download this repository to your computer:
  39. ```bash
  40. git clone https://github.com/jjsantos01/jupyter-notebook-mcp.git
  41. ```
  42. 2. Create virtual environment with required packages an install `jupyter-mcp` kernel, so it can be recognized by your jupyter installation, if you had one before.
  43. ```bash
  44. uv run python -m ipykernel install --name jupyter-mcp
  45. ```
  46. 3. (optional) Install additional Python packages for your analysis:
  47. ```bash
  48. uv pip install seaborn
  49. ```
  50. 4. Configure Claude desktop integration:
  51. Go to `Claude` > `Settings` > `Developer` > `Edit Config` > `claude_desktop_config.json` to include the following:
  52. ```json
  53. {
  54. "mcpServers": {
  55. "jupyter": {
  56. "command": "uv",
  57. "args": [
  58. "--directory",
  59. "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/src",
  60. "run",
  61. "jupyter_mcp_server.py"
  62. ]
  63. }
  64. }
  65. }
  66. ```
  67. Replace `/ABSOLUTE/PATH/TO/` with the actual path to the `src` folder on your system. For example:
  68. - Windows: `"C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"`
  69. - Mac: `/Users/MyUser/GitHub/jupyter-notebook-mcp/src/`
  70. If you had previously opened Claude, then `File` > `Exit` and open it again.
  71. ## Usage
  72. ### Starting the Connection
  73. 1. Start your Jupyter Notebook (version 6.x) server:
  74. ```bash
  75. uv run jupyter nbclassic
  76. ```
  77. 2. Create a new Jupyter Notebook and make sure that you choose the `jupyter-mcp` kernel: `kernel` -> `change kernel` -> `jupyter-mcp`
  78. 3. In a notebook cell, run the following code to initialize the WebSocket server:
  79. ```python
  80. import sys
  81. sys.path.append('/path/to/jupyter-notebook-mcp/src') # Add the path to where the scripts are located
  82. from jupyter_ws_server import setup_jupyter_mcp_integration
  83. # Start the WebSocket server inside Jupyter
  84. server, port = setup_jupyter_mcp_integration()
  85. ```
  86. Don't forget to replace here `'/path/to/jupyter-notebook-mcp/src'` with `src` folder on your system. For example:
  87. - Windows: `"C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"`
  88. - Mac: `/Users/MyUser/GitHub/jupyter-notebook-mcp/src/`
  89. ![Notebook setup](/assets/img/notebook-setup.png)
  90. 4. Launch Claude desktop with MCP enabled.
  91. ### Using with Claude
  92. Once connected, Claude will have access to the following tools:
  93. - `ping` - Check server connectivity
  94. - `insert_and_execute_cell` - Insert a cell at the specified position and execute it
  95. - `save_notebook` - Save the current Jupyter notebook
  96. - `get_cells_info` - Get information about all cells in the notebook
  97. - `get_notebook_info` - Get information about the current notebook
  98. - `run_cell` - Run a specific cell by its index
  99. - `run_all_cells` - Run all cells in the notebook
  100. - `get_cell_text_output` - Get the output content of a specific cell
  101. - `get_image_output` - Get the images output of a specific cell
  102. - `edit_cell_content` - Edit the content of an existing cell
  103. - `set_slideshow_type`- Set the slide show type for cell
  104. ## ⚠️ DISCLAIMER
  105. This is an experimental project and should be used with caution. This tool runs arbitrary Python code in your computer, which could potentially modify or delete data if not used carefully. Always back up your important projects and data.
  106. ## Example Prompts
  107. Ask Claude to perform notebook operations:
  108. ### Python example
  109. You can check the [example notebook](/notebooks/example_notebook.ipynb) and the [video demo](https://x.com/jjsantoso/status/1906780778807390562)
  110. ```plain
  111. You have access to a Jupyter Notebook server.
  112. I need to create a presentation about Python's Seaborn library.
  113. The content is as follows:
  114. - What is Seaborn?
  115. - Long vs. Wide data format
  116. - Advantages of Seaborn over Matplotlib
  117. - Commonly used Seaborn functions
  118. - Live demonstration (comparison of Seaborn vs. Matplotlib)
  119. - Bar plot
  120. - Line plot
  121. - Scatter plot
  122. For each concept, I want the main explanations provided in markdown cells, followed by one or more Python code cells demonstrating its usage. Keep the text concise—the cells shouldn't exceed 10 lines each.
  123. Use appropriate slideshow types for each cell to make the presentation visually appealing.
  124. ```
  125. [Check Here the full conversation](https://claude.ai/share/420b6aa6-b84b-437f-a6a6-89d310c36d52)
  126. ### Stata example
  127. For this example, you need the [Stata Software](https://www.stata.com/) (v17 or later), which is not open source. If you already have Stata, you need to install the [`stata-setup`](https://pypi.org/project/stata-setup/) package:
  128. ```bash
  129. uv pip install stata-setup
  130. ```
  131. Then, at the begining of your notebook, you need to additionally include:
  132. ```python
  133. import stata_setup
  134. stata_setup.config('your_stata_installation_directory', 'your_stata_edition')
  135. ```
  136. You can check the [example notebook](/notebooks/stata_example.ipynb) and the [video demo](https://x.com/jjsantoso/status/1906780784800731251)
  137. This exercise comes from [Professor John Robert Warren webpage](https://www.rob-warren.com/soc3811_stata_exercises.html)
  138. ```plain
  139. You have access to a Jupyter Notebook server. By default it runs Python, but you can run Stata (v18) code in this server using the %%stata magic, for example:
  140. %%stata
  141. display "hello world"
  142. Run the available tools to solve the exercise, execute the code, and interpret the results.
  143. **EXERCISE:**
  144. In this exercise, you will use data from the American Community Survey (ACS). The ACS is a product of the U.S. Census Bureau and involves interviewing millions of Americans each year. For an introduction to the ACS, visit the ACS website (here).
  145. For this exercise, I have created a data file containing two variables collected from respondents of the 2010 ACS who lived in one of two metropolitan areas: Minneapolis/St Paul and Duluth/Superior. The two variables are: (1) People's poverty status and (2) the time it takes people to commute to work.
  146. Use STATA syntax files you already have (from the first assignment or class examples) and modify them to accomplish the following goals.
  147. 1. Read the data file (`"./stata_assignment_2.dat"`) for this assignment into STATA.
  148. 2. Be sure to declare "zero" as a missing value for `TRANTIME`, the commuting time variable.
  149. 3. Create a new dichotomous poverty variable that equals "1" if a person's income-to-poverty-line ratio (`POVRATIO`) is less than 100, and "0" otherwise; see the bottom of the assignment for an example of how to do this in STATA.
  150. 4. Separately for Minneapolis/St Paul and Duluth/Superior, produce:
  151. - a histogram of the commuting time (`TRANTIME`) variable.
  152. - measures of central tendency and spread for commuting time.
  153. - a frequency distribution for the poverty status (0 vs 1) variable.
  154. 5. Separately for Minneapolis/St Paul and Duluth/Superior, use STATA code to produce:
  155. - a 95% confidence interval for the mean commuting time.
  156. - a 95% confidence interval for the proportion of people who are poor. See below for an example of how to do this in STATA.
  157. Use the results from step #4 above to:
  158. 6. Separately for Minneapolis/St Paul and Duluth/Superior, manually calculate:
  159. - a 95% confidence interval for the mean commuting time.
  160. - a 95% confidence interval for the proportion of people who are poor.
  161. 7. Confirm that your answers from steps #5 and #6 match.
  162. Based on the results above, answer this question:
  163. 8. How do you interpret the confidence intervals calculated in steps #5 and #6 above?
  164. 9. Finally, create a do file (.do) with the all the Stata code and the answers as comments.
  165. ---
  166. **DESCRIPTION OF VARIABLES IN "STATA ASSIGNMENT 2.DAT"**
  167. **METAREAD** (Column 4-7)
  168. Metropolitan Area
  169. - `2240`: Duluth-Superior, MN/WI
  170. - `5120`: Minneapolis-St. Paul, MN
  171. **POVRATIO** (Column 18-20)
  172. Ratio of person's income to the poverty threshold:
  173. - `<100`: Below Poverty Line
  174. - `100`: At Poverty Line
  175. - `>100`: Above Poverty Line
  176. **TRANTIME** (Column 21-23)
  177. Travel time to work
  178. - `0`: Zero minutes
  179. - `1`: 1 Minute
  180. - etc.
  181. ```
  182. [Check Here the full conversation](https://claude.ai/share/97b5a546-9375-434d-8224-561706782880)
  183. ## Testing with External Client
  184. You can test the functionality without using Claude Desktop with the included external client:
  185. ```bash
  186. uv run python src/jupyter_ws_external_client.py
  187. ```
  188. This will provide an interactive menu to test some available functions.
  189. For automated testing of all commands:
  190. ```bash
  191. uv run python src/jupyter_ws_external_client.py --batch
  192. ```
  193. ## Troubleshooting
  194. - **Connection Issues**: If you experience connection timeouts, the client includes a reconnection mechanism. You can also try restarting the WebSocket server.
  195. - **Cell Execution Problems**: If cell execution doesn't work, check that the cell content is valid Python/Markdown and that the notebook kernel is running.
  196. - **WebSocket Port Conflicts**: If the default port (8765) is already in use, the server will automatically try to find an available port.
  197. ## Limitations
  198. - Only supports Jupyter Notebook 6.x
  199. - Text output from cells is limited to 1500 characters by default
  200. - Does not support advanced Jupyter widget interactions
  201. - Connection may timeout after periods of inactivity
  202. ## License
  203. [MIT](/LICENSE)
  204. ## Other Jupyter MCPs
  205. This project is inspired by similar MCP integrations for Jupyter as:
  206. - [ihrpr](https://github.com/ihrpr/mcp-server-jupyter)
  207. - [Datalayer](https://github.com/datalayer/jupyter-mcp-server/tree/main)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.