Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 14 additions & 15 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -116,21 +116,20 @@ jobs:
id: version
run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT

- name: Create Release with Auto-Generated Notes
run: |
gh release create ${{ github.ref_name }} \
--title "Release ${{ steps.version.outputs.VERSION }}" \
--generate-notes \
--notes "## 🚀 Release ${{ steps.version.outputs.VERSION }}

### 🔗 Links

- [PyPI](https://pypi.org/project/jupyter-mcp-server/${{ steps.version.outputs.VERSION }}/)
- [Docker Hub](https://hub.docker.com/r/datalayer/jupyter-mcp-server)

- name: Create Release
uses: actions/create-release@v1
---

### What's Changed"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
tag_name: ${{ github.ref }}
release_name: Release ${{ steps.version.outputs.VERSION }}
body: |
## 🚀 Release ${{ steps.version.outputs.VERSION }}

### 🔗 Links

- [PyPI](https://pypi.org/project/jupyter-mcp-server/${{ steps.version.outputs.VERSION }}/)
- [Docker Hub](https://hub.docker.com/r/datalayer/jupyter-mcp-server)
draft: false
prerelease: false
generate_release_notes: true
14 changes: 11 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
<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>


> 🚨 **Latest Release: v0.14.0**: **Multi-notebook support!** You can now seamlessly switch between multiple notebooks in a single session. [📋 Read more in the release notes](https://jupyter-mcp-server.datalayer.tech/releases)
> 🚨 **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)

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

Expand All @@ -42,14 +42,14 @@
- [Contributing](#-contributing)
- [Resources](#-resources)


## 🚀 Key Features

- ⚡ **Real-time control:** Instantly view notebook changes as they happen.
- 🔁 **Smart execution:** Automatically adjusts when a cell run fails thanks to cell output feedback.
- 🧠 **Context-aware:** Understands the entire notebook context for more relevant interactions.
- 📊 **Multimodal support:** Support different output types, including images, plots, and text.
- 📚 **Multi-notebook support:** Seamlessly switch between multiple notebooks.
- 🎨 **JupyterLab integration:** Enhanced UI integration like automatic notebook opening.
- 🤝 **MCP-compatible:** Works with any MCP client, such as Claude Desktop, Cursor, Windsurf, and more.

Compatible with any Jupyter deployment (local, JupyterHub, ...) and with [Datalayer](https://datalayer.ai/) hosted Notebooks.
Expand Down Expand Up @@ -89,6 +89,14 @@ The server provides a rich set of tools for interacting with Jupyter notebooks,
| `insert_execute_code_cell` | A convenient tool to insert a new code cell and execute it in one step. |
| `execute_ipython` | Execute IPython code directly in the kernel, including magic and shell commands. |

### JupyterLab Integration

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

| Name | Description |
|:---|:---|
| `notebook_run-all-cells` | Execute all cells in the current notebook sequentially using JupyterLab's native commands. |

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).

## 🏁 Getting Started
Expand All @@ -98,7 +106,7 @@ For comprehensive setup instructions—including `Streamable HTTP` transport, ru
### 1. Set Up Your Environment

```bash
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 ipykernel
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17
```
Expand Down
3 changes: 3 additions & 0 deletions docs/docs/configure/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ Options:
Defaults to 'stdio'.
--provider [jupyter|datalayer] The provider to use for the document and
runtime. Defaults to 'jupyter'.
--jupyterlab BOOLEAN Enable JupyterLab mode for enhanced UI
integration like automatic notebook opening.
Defaults to True.
--runtime-url TEXT The runtime URL to use. For the jupyter
provider, this is the Jupyter server URL.
For the datalayer provider, this is the
Expand Down
6 changes: 6 additions & 0 deletions docs/docs/deployment/jupyter/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ The Jupyter MCP Server acts as a bridge between the MCP client and the JupyterLa

You can customize the setup further based on your requirements. Refer to the [server configuration](/configure) for more details on the possible configurations.

:::tip JupyterLab Mode

**New in v0.17.0**: Enable JupyterLab mode for enhanced UI integration! When enabled, notebooks automatically open in JupyterLab and additional UI tools become available. See the [JupyterLab Mode configuration](/configure#jupyterlab-mode) for details.

:::

Jupyter MCP Server supports two types of transport to connect to your MCP client: **STDIO** and **Streamable HTTP**. Choose the one that best fits your needs.
For more details on the different transports, refer to the official MCP documentation [here](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports).

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/deployment/jupyter/stdio/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
Make sure you have the following packages installed in your environment. The collaboration package is needed as the modifications made on the notebook can be seen thanks to [Jupyter Real Time Collaboration](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html).

```bash
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 ipykernel
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Make sure you have the following packages installed in your environment. The col
```bash
pip install "jupyter-mcp-server>=0.15.0" "jupyterlab==4.4.1" "jupyter-collaboration==4.0.2" "ipykernel"
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17
pip install datalayer_pycrdt==0.12.17 jupyter_mcp_tools
```

### JupyterLab and MCP start
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
Make sure you have the following packages installed in your environment. The collaboration package is needed as the modifications made on the notebook can be seen thanks to [Jupyter Real Time Collaboration](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html).

```bash
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 ipykernel
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17
```
Expand Down
1 change: 1 addition & 0 deletions docs/docs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ Key features include:
- 🧠 **Context-aware:** Understands the entire notebook context for more relevant interactions.
- 📊 **Multimodal support:** Support different output types, including images, plots, and text.
- 📁 **Multi-notebook support:** Seamlessly switch between multiple notebooks.
- 🎛️ **JupyterLab integration:** Enhanced UI integration like automatic notebook opening.
- 🤝 **MCP-compatible:** Works with any MCP client, such as [Claude Desktop](/clients/claude_desktop), [Cursor](/clients/cursor), [Cline](/clients/cline), [Windsurf](/clients/windsurf) and more.

To use Jupyter MCP Server, you first need to decide which setup fits your needs:
Expand Down
26 changes: 16 additions & 10 deletions docs/docs/releases/index.mdx
Original file line number Diff line number Diff line change
@@ -1,48 +1,54 @@
# Releases

## 0.16.x - 13 Oct 2025
## Latest Release

See the latest release notes on the [GitHub Releases page](https://github.com/datalayer/jupyter-mcp-server/releases).

## Older Releases

### 0.16.x - 13 Oct 2025

- [Merge the three execute tools into a single unified tool](https://github.com/datalayer/jupyter-mcp-server/pull/111)

## 0.15.x - 08 Oct 2025
### 0.15.x - 08 Oct 2025

- [Run as Jupyter Server Extension + Tool registry + Use tool](https://github.com/datalayer/jupyter-mcp-server/pull/95)
- [simplify tool implementations](https://github.com/datalayer/jupyter-mcp-server/pull/101)
- [add uvx as alternative MCP server startup method](https://github.com/datalayer/jupyter-mcp-server/pull/101)
- [document as a Jupyter Extension](https://github.com/datalayer/jupyter-mcp-server/pull/101)
- Fix Minor Bugs: [#108](https://github.com/datalayer/jupyter-mcp-server/pull/108),[#110](https://github.com/datalayer/jupyter-mcp-server/pull/110)

## 0.14.0 - 03 Oct 2025
### 0.14.0 - 03 Oct 2025

- [Additional Tools & Bug fixes](https://github.com/datalayer/jupyter-mcp-server/pull/93).
- [Execute IPython](https://github.com/datalayer/jupyter-mcp-server/pull/90).
- [Multi notebook management](https://github.com/datalayer/jupyter-mcp-server/pull/88).

## 0.13.0 - 25 Sep 2025
### 0.13.0 - 25 Sep 2025

- [Add multimodal output support for Jupyter cell execution](https://github.com/datalayer/jupyter-mcp-server/pull/75).
- [Unify cell insertion functionality](https://github.com/datalayer/jupyter-mcp-server/pull/73).

## 0.11.0 - 01 Aug 2025
### 0.11.0 - 01 Aug 2025

- [Rename room to document](https://github.com/datalayer/jupyter-mcp-server/pull/35).

## 0.10.2 - 17 Jul 2025
### 0.10.2 - 17 Jul 2025

- [Tools docstring improvements](https://github.com/datalayer/jupyter-mcp-server/pull/30).

## 0.10.1 - 11 Jul 2025
### 0.10.1 - 11 Jul 2025

- [CORS Support](https://github.com/datalayer/jupyter-mcp-server/pull/29).

## 0.10.0 - 07 Jul 2025
### 0.10.0 - 07 Jul 2025

- More [fixes](https://github.com/datalayer/jupyter-mcp-server/pull/28) issues for nbclient stop.

## 0.9.0 - 02 Jul 2025
### 0.9.0 - 02 Jul 2025

- Fix issues with `nbmodel` stops.

## 0.6.0 - 01 Jul 2025
### 0.6.0 - 01 Jul 2025

- Configuration change, see details on the [clients page](/clients) and [server configuration](/configure).
15 changes: 14 additions & 1 deletion docs/docs/tools/index.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Tools

The server currently offers 16 tools organized into 3 categories:
The server currently offers 16 tools organized into 3 categories, plus 1 additional JupyterLab-specific tool:

## Server Management Tools (3 tools)

Expand Down Expand Up @@ -164,3 +164,16 @@ The server currently offers 16 tools organized into 3 categories:
- `timeout`(int): Execution timeout in seconds (default: 60s)
- Returns:
- `list[Union[str, ImageContent]]`: List of outputs from the executed code (supports multimodal output including images)

## JupyterLab-Specific Tools (1 tool)

*Available only when JupyterLab mode is enabled (`--jupyterlab` or `jupyterlab: true` in config). It is set to `True` by default.*

#### 17. `notebook_run-all-cells`

- Execute all cells in the current notebook sequentially.
- This tool provides a convenient way to run the entire notebook from start to finish, which is particularly useful for batch execution or notebook validation.
- Only available when JupyterLab mode is enabled for enhanced UI integration.
- Input: None
- Returns: Success message indicating that all cells have been executed
- Note: This tool uses JupyterLab's native execution commands for optimal performance and UI feedback.
12 changes: 6 additions & 6 deletions docs/docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ module.exports = {
'aria-label': 'YouTube',
},
{
href: 'https://datalayer.io',
href: 'https://datalayer.ai',
position: 'right',
className: 'header-datalayer-io-link',
'aria-label': 'Datalayer',
Expand Down Expand Up @@ -125,16 +125,16 @@ module.exports = {
},
{
label: 'Datalayer Docs',
href: 'https://docs.datalayer.ai',
},
{
label: 'Datalayer Blog',
href: 'https://datalayer.blog',
href: 'https://docs.datalayer.app',
},
{
label: 'Datalayer Guide',
href: 'https://datalayer.guide',
},
{
label: 'Datalayer Blog',
href: 'https://datalayer.blog',
},
],
},
],
Expand Down
19 changes: 17 additions & 2 deletions jupyter_mcp_server/CLI.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,13 @@ def _common_options(f):
default="jupyter",
help="The provider to use for the document and runtime. Defaults to 'jupyter'.",
),
click.option(
"--jupyterlab",
envvar="JUPYTERLAB",
type=click.BOOL,
default=True,
help="Enable JupyterLab mode. Defaults to True.",
),
click.option(
"--runtime-url",
envvar="RUNTIME_URL",
Expand Down Expand Up @@ -157,6 +164,7 @@ def _do_start(
document_token: str,
port: int,
provider: str,
jupyterlab: bool,
):
"""Internal function to execute the start logic."""

Expand All @@ -180,7 +188,8 @@ def _do_start(
document_url=document_url,
document_id=document_id,
document_token=document_token,
port=port
port=port,
jupyterlab=jupyterlab
)

# Reset ServerContext to pick up new configuration
Expand Down Expand Up @@ -259,6 +268,7 @@ def server(
jupyter_token: str,
port: int,
provider: str,
jupyterlab: bool,
):
"""Manages Jupyter MCP Server.

Expand Down Expand Up @@ -293,6 +303,7 @@ def server(
document_token=resolved_document_token,
port=port,
provider=provider,
jupyterlab=jupyterlab,
)


Expand All @@ -314,6 +325,7 @@ def connect_command(
document_id: str,
document_token: str,
provider: str,
jupyterlab: bool,
):
"""Command to connect a Jupyter MCP Server to a document and a runtime."""

Expand All @@ -325,7 +337,8 @@ def connect_command(
runtime_token=runtime_token,
document_url=document_url,
document_id=document_id,
document_token=document_token
document_token=document_token,
jupyterlab=jupyterlab
)

config = get_config()
Expand Down Expand Up @@ -402,6 +415,7 @@ def start_command(
jupyter_token: str,
port: int,
provider: str,
jupyterlab: bool,
):
"""Start the Jupyter MCP server with a transport."""
# Resolve URL and token variables based on priority logic
Expand All @@ -425,6 +439,7 @@ def start_command(
document_token=resolved_document_token,
port=port,
provider=provider,
jupyterlab=jupyterlab,
)


Expand Down
5 changes: 5 additions & 0 deletions jupyter_mcp_server/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ class JupyterMCPConfig(BaseModel):

# Server configuration
port: int = Field(default=4040, description="The port to use for the Streamable HTTP transport")
jupyterlab: bool = Field(default=True, description="Enable JupyterLab mode (defaults to True)")

class Config:
"""Pydantic configuration."""
Expand All @@ -42,6 +43,10 @@ def is_local_document(self) -> bool:
def is_local_runtime(self) -> bool:
"""Check if runtime URL is set to local."""
return self.runtime_url == "local"

def is_jupyterlab_mode(self) -> bool:
"""Check if JupyterLab mode is enabled."""
return self.jupyterlab

def _get_env_bool(env_name: str, default_value: bool = True) -> bool:
"""
Expand Down
Loading
Loading