Skip to content

Commit b0f1b16

Browse files
eleonorecharleseleonorecharles
authored
Ft/docs improv (#131)
* docs * clean release notes * layout * layout * layout * layout * layout * layout * layout
1 parent 3f49022 commit b0f1b16

File tree

7 files changed

+465
-187
lines changed

7 files changed

+465
-187
lines changed

‎.github/workflows/release.yml‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -127,9 +127,5 @@ jobs:
127127
128128
- [PyPI](https://pypi.org/project/jupyter-mcp-server/${{ steps.version.outputs.VERSION }}/)
129129
- [Docker Hub](https://hub.docker.com/r/datalayer/jupyter-mcp-server)
130-
131-
---
132-
133-
### What's Changed"
134130
env:
135131
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎README.md‎

Lines changed: 53 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@
88

99
[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)
1010

11-
1211
<div align="center">
1312

1413
<!-- omit in toc -->
14+
1515
# 🪐✨ Jupyter MCP Server
1616

1717
**An [MCP](https://modelcontextprotocol.io) server developed for AI to connect and manage Jupyter Notebooks in real-time**
@@ -23,18 +23,31 @@
2323
[![Docker Pulls](https://img.shields.io/docker/pulls/datalayer/jupyter-mcp-server?style=for-the-badge&logo=docker&logoColor=white&color=2496ED)](https://hub.docker.com/r/datalayer/jupyter-mcp-server)
2424
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue?style=for-the-badge&logo=open-source-initiative&logoColor=white)](https://opensource.org/licenses/BSD-3-Clause)
2525

26+
<table>
27+
<tr>
28+
<td width="60%">
2629

27-
<a href="https://mseep.ai/app/datalayer-jupyter-mcp-server"><img src="https://mseep.net/pr/datalayer-jupyter-mcp-server-badge.png" alt="MseeP.ai Security Assessment Badge" width="100"></a>
28-
<a href="https://archestra.ai/mcp-catalog/datalayer__jupyter-mcp-server"><img src="https://archestra.ai/mcp-catalog/api/badge/quality/datalayer/jupyter-mcp-server" alt="Trust Score" width="150"></a>
30+
📢 **Upcoming JupyterCon 2025**: We'll be presenting Jupyter MCP Server at [JupyterCon 2025](https://jupytercon2025.sched.com/event/28H3z) on November 4! Join us to learn about ✨ AI-powered notebook interactions and the future of 🪐 Jupyter workflows.
2931

32+
</td>
33+
<td width="40%" align="center">
3034

31-
> 🚨 **Latest Release: v17.0**: **JupyterLab Mode Integration!** Enhanced UI integration with automatic notebook opening. [📋 Read more in the release notes](https://jupyter-mcp-server.datalayer.tech/releases)
35+
<a href="https://jupytercon2025.sched.com/event/28H3z">
36+
<img src="https://assets.datalayer.tech/jupyter-mcp/JupyterCon.png" alt="JupyterCon 2025" width="400">
37+
</a>
38+
39+
</td>
40+
</tr>
41+
</table>
3242

3343
![Jupyter MCP Server Demo](https://assets.datalayer.tech/jupyter-mcp/mcp-demo-multimodal.gif)
3444

45+
> 🚨 **Latest Release: v17.0**: **JupyterLab Mode Integration!** Enhanced UI integration with automatic notebook opening. [📋 Read more in the release notes](https://jupyter-mcp-server.datalayer.tech/releases)
46+
3547
</div>
3648

3749
## 📖 Table of Contents
50+
3851
- [Key Features](#-key-features)
3952
- [Tools Overview](#-tools-overview)
4053
- [Getting Started](#-getting-started)
@@ -60,41 +73,41 @@ The server provides a rich set of tools for interacting with Jupyter notebooks,
6073

6174
### Server Management
6275

63-
| Name | Description |
64-
|:---|:---|
65-
| `list_files` | Recursively list files and directories in the Jupyter server's file system. |
66-
| `list_kernels` | List all available and running kernel sessions on the Jupyter server. |
67-
| `assign_kernel_to_notebook` | Create a Jupyter session to connect a notebook file to a specific kernel. |
76+
| Name | Description |
77+
| :-------------------------- | :-------------------------------------------------------------------------- |
78+
| `list_files` | Recursively list files and directories in the Jupyter server's file system. |
79+
| `list_kernels` | List all available and running kernel sessions on the Jupyter server. |
80+
| `assign_kernel_to_notebook` | Create a Jupyter session to connect a notebook file to a specific kernel. |
6881

6982
### Multi-Notebook Management
7083

71-
| Name | Description |
72-
|:---|:---|
73-
| `use_notebook` | Connect to a notebook file, create a new one, or switch between notebooks. |
74-
| `list_notebooks` | List all notebooks available on the Jupyter server and their status |
75-
| `restart_notebook` | Restart the kernel for a specific managed notebook. |
76-
| `unuse_notebook` | Disconnect from a specific notebook and release its resources. |
84+
| Name | Description |
85+
| :----------------- | :------------------------------------------------------------------------- |
86+
| `use_notebook` | Connect to a notebook file, create a new one, or switch between notebooks. |
87+
| `list_notebooks` | List all notebooks available on the Jupyter server and their status |
88+
| `restart_notebook` | Restart the kernel for a specific managed notebook. |
89+
| `unuse_notebook` | Disconnect from a specific notebook and release its resources. |
7790

7891
### Cell Operations and Execution
7992

80-
| Name | Description |
81-
|:---|:---|
82-
| `list_cells` | List basic information for all cells to provide a quick overview of notebook |
83-
| `read_cell` | Read the full content (source and outputs) of a single cell. |
84-
| `read_cells` | Read the full content of all cells in the notebook. |
85-
| `insert_cell` | Insert a new code or markdown cell at a specified position. |
86-
| `delete_cell` | Delete a cell at a specified index. |
87-
| `overwrite_cell_source` | Overwrite the source code of an existing cell. |
88-
| `execute_cell` | Execute a cell with timeout, it supports multimodal output including images. |
89-
| `insert_execute_code_cell` | A convenient tool to insert a new code cell and execute it in one step. |
90-
| `execute_ipython` | Execute IPython code directly in the kernel, including magic and shell commands. |
93+
| Name | Description |
94+
| :------------------------- | :------------------------------------------------------------------------------- |
95+
| `list_cells` | List basic information for all cells to provide a quick overview of notebook |
96+
| `read_cell` | Read the full content (source and outputs) of a single cell. |
97+
| `read_cells` | Read the full content of all cells in the notebook. |
98+
| `insert_cell` | Insert a new code or markdown cell at a specified position. |
99+
| `delete_cell` | Delete a cell at a specified index. |
100+
| `overwrite_cell_source` | Overwrite the source code of an existing cell. |
101+
| `execute_cell` | Execute a cell with timeout, it supports multimodal output including images. |
102+
| `insert_execute_code_cell` | A convenient tool to insert a new code cell and execute it in one step. |
103+
| `execute_ipython` | Execute IPython code directly in the kernel, including magic and shell commands. |
91104

92105
### JupyterLab Integration
93106

94107
*Available only when JupyterLab mode is enabled. It is enabled by default.*
95108

96-
| Name | Description |
97-
|:---|:---|
109+
| Name | Description |
110+
| :----------------------- | :----------------------------------------------------------------------------------------- |
98111
| `notebook_run-all-cells` | Execute all cells in the current notebook sequentially using JupyterLab's native commands. |
99112

100113
For more details on each tool, their parameters, and return values, please refer to the [official Tools documentation](https://jupyter-mcp-server.datalayer.tech/tools).
@@ -135,14 +148,17 @@ Next, configure your MCP client to connect to the server. We offer two primary m
135148
<summary><b>📦 Using uvx (Quick Start)</b></summary>
136149

137150
First, install `uv`:
151+
138152
```bash
139153
pip install uv
140154
uv --version
141155
# should be 0.6.14 or higher
142156
```
157+
143158
See more details on [uv installation](https://docs.astral.sh/uv/getting-started/installation/).
144159

145160
Then, configure your client:
161+
146162
```json
147163
{
148164
"mcpServers": {
@@ -165,6 +181,7 @@ Then, configure your client:
165181
<summary><b>🐳 Using Docker (Production)</b></summary>
166182

167183
**On macOS and Windows:**
184+
168185
```json
169186
{
170187
"mcpServers": {
@@ -188,6 +205,7 @@ Then, configure your client:
188205
```
189206

190207
**On Linux:**
208+
191209
```json
192210
{
193211
"mcpServers": {
@@ -214,11 +232,12 @@ Then, configure your client:
214232
</details>
215233

216234
> [!TIP]
235+
>
217236
> 1. **Port Configuration**: Ensure the `port` in your Jupyter URLs matches the one used in the `jupyter lab` command. For simplified config, set this in `JUPYTER_URL`.
218-
> 2. **Server Separation**: Use `JUPYTER_URL` when both services are on the same server, or set individual variables for advanced deployments. The different URL variables exist because some deployments separate notebook storage (`DOCUMENT_URL`) from kernel execution (`RUNTIME_URL`).
219-
> 3. **Authentication**: In most cases, document and runtime services use the same authentication token. Use `JUPYTER_TOKEN` for simplified config or set `DOCUMENT_TOKEN` and `RUNTIME_TOKEN` individually for different credentials.
220-
> 4. **Notebook Path**: The `DOCUMENT_ID` parameter specifies the path to the notebook the MCP client default to connect. It should be relative to the directory where JupyterLab was started. If you omit `DOCUMENT_ID`, the MCP client can automatically list all available notebooks on the Jupyter server, allowing you to select one interactively via your prompts.
221-
> 5. **Image Output**: Set `ALLOW_IMG_OUTPUT` to `false` if your LLM does not support mutimodel understanding.
237+
> 1. **Server Separation**: Use `JUPYTER_URL` when both services are on the same server, or set individual variables for advanced deployments. The different URL variables exist because some deployments separate notebook storage (`DOCUMENT_URL`) from kernel execution (`RUNTIME_URL`).
238+
> 1. **Authentication**: In most cases, document and runtime services use the same authentication token. Use `JUPYTER_TOKEN` for simplified config or set `DOCUMENT_TOKEN` and `RUNTIME_TOKEN` individually for different credentials.
239+
> 1. **Notebook Path**: The `DOCUMENT_ID` parameter specifies the path to the notebook the MCP client default to connect. It should be relative to the directory where JupyterLab was started. If you omit `DOCUMENT_ID`, the MCP client can automatically list all available notebooks on the Jupyter server, allowing you to select one interactively via your prompts.
240+
> 1. **Image Output**: Set `ALLOW_IMG_OUTPUT` to `false` if your LLM does not support mutimodel understanding.
222241
223242
For detailed instructions on configuring various MCP clients—including [Claude Desktop](https://jupyter-mcp-server.datalayer.tech/clients/claude_desktop), [VS Code](https://jupyter-mcp-server.datalayer.tech/clients/vscode), [Cursor](https://jupyter-mcp-server.datalayer.tech/clients/cursor), [Cline](https://jupyter-mcp-server.datalayer.tech/clients/cline), and [Windsurf](https://jupyter-mcp-server.datalayer.tech/clients/windsurf) — see the [Clients documentation](https://jupyter-mcp-server.datalayer.tech/clients).
224243

@@ -255,12 +274,12 @@ Looking for blog posts, videos, or other materials about Jupyter MCP Server?
255274
<img src="https://api.star-history.com/svg?repos=datalayer/jupyter-mcp-server&type=Date" alt="Star History Chart">
256275
</a>
257276

258-
---
277+
______________________________________________________________________
259278

260279
<div align="center">
261280

262281
**If this project is helpful to you, please give us a ⭐️**
263282

264283
Made with ❤️ by [Datalayer](https://github.com/datalayer)
265284

266-
</div>
285+
</div>

‎docs/docs/clients/vscode/index.mdx‎

Lines changed: 85 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,43 @@ Open your `settings.json`:
3030

3131
Then add the following configuration:
3232

33+
**Simplified Configuration (Recommended):**
34+
```jsonc
35+
{
36+
"mcp": {
37+
"servers": {
38+
"DatalayerJupyter": {
39+
"command": "docker",
40+
"args": [
41+
"run",
42+
"-i",
43+
"--rm",
44+
"-e",
45+
"JUPYTER_URL",
46+
"-e",
47+
"JUPYTER_TOKEN",
48+
"-e",
49+
"DOCUMENT_ID",
50+
"-e",
51+
"ALLOW_IMG_OUTPUT",
52+
"datalayer/jupyter-mcp-server:latest"
53+
],
54+
"env": {
55+
"JUPYTER_URL": "http://host.docker.internal:8888",
56+
"JUPYTER_TOKEN": "MY_TOKEN",
57+
"DOCUMENT_ID": "notebook.ipynb",
58+
"ALLOW_IMG_OUTPUT": "true"
59+
}
60+
}
61+
}
62+
}
63+
```
64+
65+
<details>
66+
<summary><b>Advanced Configuration (Optional)</b></summary>
67+
68+
For advanced deployments with separate document and runtime servers:
69+
3370
```jsonc
3471
{
3572
"mcp": {
@@ -50,26 +87,67 @@ Then add the following configuration:
5087
"RUNTIME_URL",
5188
"-e",
5289
"RUNTIME_TOKEN",
90+
"-e",
91+
"ALLOW_IMG_OUTPUT",
5392
"datalayer/jupyter-mcp-server:latest"
5493
],
5594
"env": {
5695
"DOCUMENT_URL": "http://host.docker.internal:8888",
5796
"DOCUMENT_TOKEN": "MY_TOKEN",
5897
"DOCUMENT_ID": "notebook.ipynb",
5998
"RUNTIME_URL": "http://host.docker.internal:8888",
60-
"RUNTIME_TOKEN": "MY_TOKEN"
99+
"RUNTIME_TOKEN": "MY_TOKEN",
100+
"ALLOW_IMG_OUTPUT": "true"
61101
}
62102
}
63103
}
64104
}
65105
```
66106
107+
</details>
108+
67109
Update with the actual configuration details from the [Jupyter MCP Server configuration](/deployment/jupyter/stdio#2-setup-jupyter-mcp-server).
68110
69111
### As Workspace Settings in `.vscode/mcp.json`
70112
71113
Open or create a `.vscode/mcp.json` file in your workspace root directory. Then add the following example configuration:
72114
115+
**Simplified Configuration (Recommended):**
116+
```jsonc
117+
{
118+
"servers": {
119+
"DatalayerJupyter": {
120+
"command": "docker",
121+
"args": [
122+
"run",
123+
"-i",
124+
"--rm",
125+
"-e",
126+
"JUPYTER_URL",
127+
"-e",
128+
"JUPYTER_TOKEN",
129+
"-e",
130+
"DOCUMENT_ID",
131+
"-e",
132+
"ALLOW_IMG_OUTPUT",
133+
"datalayer/jupyter-mcp-server:latest"
134+
],
135+
"env": {
136+
"JUPYTER_URL": "http://host.docker.internal:8888",
137+
"JUPYTER_TOKEN": "MY_TOKEN",
138+
"DOCUMENT_ID": "notebook.ipynb",
139+
"ALLOW_IMG_OUTPUT": "true"
140+
}
141+
}
142+
}
143+
}
144+
```
145+
146+
<details>
147+
<summary><b>Advanced Configuration (Optional)</b></summary>
148+
149+
For advanced deployments with separate document and runtime servers:
150+
73151
```jsonc
74152
{
75153
"servers": {
@@ -89,20 +167,25 @@ Open or create a `.vscode/mcp.json` file in your workspace root directory. Then
89167
"RUNTIME_URL",
90168
"-e",
91169
"RUNTIME_TOKEN",
170+
"-e",
171+
"ALLOW_IMG_OUTPUT",
92172
"datalayer/jupyter-mcp-server:latest"
93173
],
94174
"env": {
95175
"DOCUMENT_URL": "http://host.docker.internal:8888",
96176
"DOCUMENT_TOKEN": "MY_TOKEN",
97177
"DOCUMENT_ID": "notebook.ipynb",
98178
"RUNTIME_URL": "http://host.docker.internal:8888",
99-
"RUNTIME_TOKEN": "MY_TOKEN"
179+
"RUNTIME_TOKEN": "MY_TOKEN",
180+
"ALLOW_IMG_OUTPUT": "true"
100181
}
101182
}
102183
}
103184
}
104185
```
105186
187+
</details>
188+
106189
Update with the actual configuration details from the [Jupyter MCP Server configuration](/deployment/jupyter/stdio#2-setup-jupyter-mcp-server).
107190
108191
This enables workspace-specific configuration and sharing.

0 commit comments

Comments
 (0)