Jupyter Notebook MCP

1# JupyterMCP - Jupyter Notebook Model Context Protocol Integration
2 
3JupyterMCP 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.
4 
5## ⚠️ Compatibility Warning
6 
7**This tool is compatible ONLY with Jupyter Notebook version 6.x.**
8 
9It does NOT work with:
10 
11- Jupyter Lab
12- Jupyter Notebook v7.x
13- VS Code Notebooks
14- Google Colab
15- Any other notebook interfaces
16 
17## Features
18 
19- **Two-way communication**: Connect Claude AI to Jupyter Notebook through a WebSocket-based server
20- **Cell manipulation**: Insert, execute, and manage notebook cells
21- **Notebook management**: Save notebooks and retrieve notebook information
22- **Cell execution**: Run specific cells or execute all cells in a notebook
23- **Output retrieval**: Get output content from executed cells with text limitation options
24 
25## Components
26 
27The system consists of three main components:
28 
291. **WebSocket Server (`jupyter_ws_server.py`)**: Sets up a WebSocket server inside Jupyter that bridges communication between notebook and external clients
302. **Client JavaScript (`client.js`)**: Runs in the notebook to handle operations (inserting cells, executing code, etc.)
313. **MCP Server (`jupyter_mcp_server.py`)**: Implements the Model Context Protocol and connects to the WebSocket server
32 
33## Installation
34 
35### Prerequisites
36 
37- [Python 3.12 or newer](https://www.python.org/downloads/) (probably also work with older versions, but not tested)
38- [`uv` package manager](/README.md#installing-uv)
39- [Claude AI desktop application](https://claude.ai/download)
40 
41#### Installing uv
42 
43If you're on Mac:
44 
45```bash
46brew install uv
47```
48 
49On Windows (PowerShell):
50 
51```bash
52powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
53```
54 
55For other platforms, see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
56 
57### Setup
58 
591. Clone or download this repository to your computer:
60 
61   ```bash
62   git clone https://github.com/jjsantos01/jupyter-notebook-mcp.git
63   ```
64 
652. 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.
66 
67   ```bash
68   uv run python -m ipykernel install --name jupyter-mcp
69   ```
70 
713. (optional) Install additional Python packages for your analysis:
72 
73   ```bash
74   uv pip install seaborn
75   ```
76 
774. Configure Claude desktop integration:
78   Go to `Claude` > `Settings` > `Developer` > `Edit Config` > `claude_desktop_config.json` to include the following:
79 
80   ```json
81      {
82       "mcpServers": {
83           "jupyter": {
84               "command": "uv",
85               "args": [
86                   "--directory",
87                   "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/src",
88                   "run",
89                   "jupyter_mcp_server.py"
90               ]
91           }
92       }
93   }
94   ```
95 
96   Replace `/ABSOLUTE/PATH/TO/` with the actual path to the `src` folder on your system. For example:
97   - Windows: `"C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"`
98   - Mac: `/Users/MyUser/GitHub/jupyter-notebook-mcp/src/`
99 
100   If you had previously opened Claude, then `File` > `Exit` and open it again.
101 
102## Usage
103 
104### Starting the Connection
105 
1061. Start your Jupyter Notebook (version 6.x) server:
107 
108   ```bash
109   uv run jupyter nbclassic
110   ```
111 
1122. Create a new Jupyter Notebook and make sure that you choose the `jupyter-mcp` kernel: `kernel` -> `change kernel` -> `jupyter-mcp`
113 
1143. In a notebook cell, run the following code to initialize the WebSocket server:
115 
116   ```python
117   import sys
118   sys.path.append('/path/to/jupyter-notebook-mcp/src')  # Add the path to where the scripts are located
119   
120   from jupyter_ws_server import setup_jupyter_mcp_integration
121   
122   # Start the WebSocket server inside Jupyter
123   server, port = setup_jupyter_mcp_integration()
124   ```
125 
126   Don't forget to replace here `'/path/to/jupyter-notebook-mcp/src'` with `src` folder on your system. For example:
127   - Windows: `"C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"`
128   - Mac: `/Users/MyUser/GitHub/jupyter-notebook-mcp/src/`
129 
130   ![Notebook setup](/assets/img/notebook-setup.png)
131 
1324. Launch Claude desktop with MCP enabled.
133 
134### Using with Claude
135 
136Once connected, Claude will have access to the following tools:
137 
138- `ping` - Check server connectivity
139- `insert_and_execute_cell` - Insert a cell at the specified position and execute it
140- `save_notebook` - Save the current Jupyter notebook
141- `get_cells_info` - Get information about all cells in the notebook
142- `get_notebook_info` - Get information about the current notebook
143- `run_cell` - Run a specific cell by its index
144- `run_all_cells` - Run all cells in the notebook
145- `get_cell_text_output` - Get the output content of a specific cell
146- `get_image_output` - Get the images output of a specific cell
147- `edit_cell_content` - Edit the content of an existing cell
148- `set_slideshow_type`- Set the slide show type for cell
149 
150## ⚠️ DISCLAIMER
151 
152This 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.
153 
154## Example Prompts
155 
156Ask Claude to perform notebook operations:
157 
158### Python example
159 
160You can check the [example notebook](/notebooks/example_notebook.ipynb) and the [video demo](https://x.com/jjsantoso/status/1906780778807390562)
161 
162```plain
163You have access to a Jupyter Notebook server.
164 
165I need to create a presentation about Python's Seaborn library.  
166The content is as follows:
167 
168- What is Seaborn?
169- Long vs. Wide data format
170- Advantages of Seaborn over Matplotlib
171- Commonly used Seaborn functions
172- Live demonstration (comparison of Seaborn vs. Matplotlib)
173  - Bar plot
174  - Line plot
175  - Scatter plot
176 
177For 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.
178 
179Use appropriate slideshow types for each cell to make the presentation visually appealing.
180```
181 
182[Check Here the full conversation](https://claude.ai/share/420b6aa6-b84b-437f-a6a6-89d310c36d52)
183 
184### Stata example
185 
186For 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:
187 
188```bash
189uv pip install stata-setup
190```
191 
192Then, at the begining of your notebook, you need to additionally include:
193 
194```python
195import stata_setup
196stata_setup.config('your_stata_installation_directory', 'your_stata_edition')
197```
198 
199You can check the [example notebook](/notebooks/stata_example.ipynb) and the [video demo](https://x.com/jjsantoso/status/1906780784800731251)
200 
201This exercise comes from [Professor John Robert Warren webpage](https://www.rob-warren.com/soc3811_stata_exercises.html)
202 
203```plain
204You 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:
205 
206%%stata
207display "hello world"
208 
209Run the available tools to solve the exercise, execute the code, and interpret the results.
210 
211**EXERCISE:**
212 
213In 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).
214 
215For 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.
216 
217Use STATA syntax files you already have (from the first assignment or class examples) and modify them to accomplish the following goals.
218 
2191. Read the data file (`"./stata_assignment_2.dat"`) for this assignment into STATA.
2202. Be sure to declare "zero" as a missing value for `TRANTIME`, the commuting time variable.
2213. 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.
2224. Separately for Minneapolis/St Paul and Duluth/Superior, produce:
223   - a histogram of the commuting time (`TRANTIME`) variable.
224   - measures of central tendency and spread for commuting time.
225   - a frequency distribution for the poverty status (0 vs 1) variable.
2265. Separately for Minneapolis/St Paul and Duluth/Superior, use STATA code to produce:
227   - a 95% confidence interval for the mean commuting time.
228   - a 95% confidence interval for the proportion of people who are poor. See below for an example of how to do this in STATA.
229 
230Use the results from step #4 above to:
231 
2326. Separately for Minneapolis/St Paul and Duluth/Superior, manually calculate:
233   - a 95% confidence interval for the mean commuting time.
234   - a 95% confidence interval for the proportion of people who are poor.
2357. Confirm that your answers from steps #5 and #6 match.
236 
237Based on the results above, answer this question:
238 
2398. How do you interpret the confidence intervals calculated in steps #5 and #6 above?
240 
2419. Finally, create a do file (.do) with the all the Stata code and the answers as comments.
242 
243---
244 
245**DESCRIPTION OF VARIABLES IN "STATA ASSIGNMENT 2.DAT"**
246 
247**METAREAD** (Column 4-7)  
248Metropolitan Area  
249- `2240`: Duluth-Superior, MN/WI  
250- `5120`: Minneapolis-St. Paul, MN  
251 
252**POVRATIO** (Column 18-20)  
253Ratio of person's income to the poverty threshold:  
254- `<100`: Below Poverty Line  
255- `100`: At Poverty Line  
256- `>100`: Above Poverty Line  
257 
258**TRANTIME** (Column 21-23)  
259Travel time to work  
260- `0`: Zero minutes  
261- `1`: 1 Minute  
262- etc.
263 
264```
265 
266[Check Here the full conversation](https://claude.ai/share/97b5a546-9375-434d-8224-561706782880)
267 
268## Testing with External Client
269 
270You can test the functionality without using Claude Desktop with the included external client:
271 
272```bash
273uv run python src/jupyter_ws_external_client.py
274```
275 
276This will provide an interactive menu to test some available functions.
277 
278For automated testing of all commands:
279 
280```bash
281uv run python src/jupyter_ws_external_client.py --batch
282```
283 
284## Troubleshooting
285 
286- **Connection Issues**: If you experience connection timeouts, the client includes a reconnection mechanism. You can also try restarting the WebSocket server.
287- **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.
288- **WebSocket Port Conflicts**: If the default port (8765) is already in use, the server will automatically try to find an available port.
289 
290## Limitations
291 
292- Only supports Jupyter Notebook 6.x
293- Text output from cells is limited to 1500 characters by default
294- Does not support advanced Jupyter widget interactions
295- Connection may timeout after periods of inactivity
296 
297## License
298 
299[MIT](/LICENSE)
300 
301## Other Jupyter MCPs
302 
303This project is inspired by similar MCP integrations for Jupyter as:
304 
305- [ihrpr](https://github.com/ihrpr/mcp-server-jupyter)
306- [Datalayer](https://github.com/datalayer/jupyter-mcp-server/tree/main)
307