| Name | mcpstack-jupyter JSON |
| Version |
0.0.2
JSON |
| download |
| home_page | None |
| Summary | MCPStack delegator for jupyter-mcp-server (Option A: reuse their tools verbatim). |
| upload_time | 2025-08-21 12:50:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
mcp
mcpstack
mcppipeline
tool
template
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!--suppress HtmlDeprecatedAttribute -->
<div align="center">
<h1 align="center">
<br>
<a href="#"><img src="assets/COVER.png" alt="MCPStack Tool" width="100%"></a>
<br>
MCPStack Jupyter MCP
<br>
</h1>
<h4 align="center">Operate Jupyter Notebooks from your favourite LLM</h4>
</div>
<div align="center">
<a href="https://pre-commit.com/">
<img alt="pre-commit" src="https://img.shields.io/badge/pre--commit-enabled-1f6feb?style=for-the-badge&logo=pre-commit">
</a>
<img alt="ruff" src="https://img.shields.io/badge/Ruff-lint%2Fformat-9C27B0?style=for-the-badge&logo=ruff&logoColor=white">
<img alt="python" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white">
<img alt="pytest coverage" src="https://img.shields.io/badge/Coverage-66%25-brightgreen?style=for-the-badge&logo=pytest">
<img alt="license" src="https://img.shields.io/badge/License-MIT-success?style=for-the-badge">
</div>
> [!IMPORTANT]
> If you haven’t visited the MCPStack main orchestrator repository yet, please start
> there: **[MCPStack](https://github.com/MCP-Pipeline/MCPStack)**
## 💡 About The MCPStack Jupyter Tool
This repository provides an **MCPStack tool that wraps the official Python Jupyter MCP Server** — it is **not** a novel MCP by itself.
- Upstream project: [datalayer/jupyter-mcp-server](https://github.com/datalayer/jupyter-mcp-server)
- We **reuse their MCP actions** and surface them through **MCPStack**.
- As the upstream evolves, **some actions / endpoints may deprecate**. Our wrapper is intentionally lightweight, so updating to new upstream versions should be straightforward.
If you hit an incompatibility, **please open an issue** and we’ll track an update to align with the Jupyter MCP Server.
### What is MCPStack, in layman’s terms?
The **Model Context Protocol (MCP)** standardises how tools talk to LLMs.
`MCPStack` lets you **stack multiple MCP tools together** into a pipeline and expose them to an LLM host (e.g., Claude Desktop).
Think **scikit-learn pipelines, but for LLM tooling**:
- In scikit-learn: you chain `preprocessors` → `transformers` → `estimators`.
- In MCPStack: you chain multiple MCP tools (Jupyter, MIMIC, …) and the LLM can use all of them during a conversation.
---
## Installation
The tool is distributed as a standard Python package. Thanks to entry points, MCPStack will auto-discover it.
### Via `uv` (recommended)
```bash
uv add mcpstack-jupyter
```
### Via `pip`
```bash
pip install mcpstack-jupyter
```
### (Dev) Pre-commit hooks
```bash
uv run pre-commit install
# or: pre-commit install
```
---
## 🔌 Using With MCPStack
This tool declares entry points so MCPStack can see it automatically:
```toml
[project.entry-points."mcpstack.tools"]
jupyter = "mcpstack_jupyter.tools.jupyter.jupyter:Jupyter"
[project.entry-points."mcpstack.tool_clis"]
jupyter = "mcpstack_jupyter.tools.jupyter.cli:JupyterCLI.get_app"
```
### 1) Run Jupyter with a Token
You **must** run a Jupyter Server/Lab **with a token** (the same token will be used by both the document and runtime APIs).
```bash
uv run jupyter lab \
--port 8888 \
--IdentityProvider.token MY_TOKEN \
--ip 0.0.0.0
# MY_TOKEN can for instance be: 1117bf468693444a5608e882ab3b55d511f354a175a0df02
```
> [!NOTE]
> Docs reference: https://jupyter-mcp-server.datalayer.tech/jupyter/
Make sure to have a notebook open in Jupyter lab, e.g., `notebook.ipynb` or whatever you have defined in the configuration.
### 2) Configure the Jupyter tool (set the token)
Use the tool’s CLI to create a small `MCPStack ToolConfig` JSON. **At minimum pass `--token`**:
```bash
uv run mcpstack tools jupyter configure \
--token MY_TOKEN \
--output jupyter_config.json
# MY_TOKEN can for instance be: 1117bf468693444a5608e882ab3b55d511f354a1750df02 (must match the Jupyter server token)
```
The CLI has sensible defaults:
- `DOCUMENT_URL`: `http://127.0.0.1:8888`
- `DOCUMENT_ID`: `notebook.ipynb` <-- Feel free to change this to any of your notebooks.
- `RUNTIME_URL`: defaults to `DOCUMENT_URL`
You can override those if needed:
```bash
uv run mcpstack tools jupyter configure \
--document-url http://127.0.0.1:8888 \
--document-id Untitled.ipynb \
--runtime-url http://127.0.0.1:8888 \
--token 1117bf468693444a5608e882ab3b55d511f354a1750df02 \
--output jupyter_config.json
```
### 3) Compose a pipeline
Create a new pipeline (or append to an existing one) and include your Jupyter ToolConfig:
```bash
# New pipeline
uv run mcpstack pipeline jupyter --new-pipeline my_pipeline.json --tool-config jupyter_config.json
# Or append to an existing pipeline
uv run mcpstack pipeline jupyter --to-pipeline my_pipeline.json --tool-config jupyter_config.json
```
### 4) Run it inside Claude Desktop (or your host)
```bash
uv run mcpstack build --pipeline my_pipeline.json --config-type claude
```
Now ask the LLM to operate the notebook. A quick smoke test:
> “Append a code cell that prints `Hello World`.”
If everything’s wired correctly, you should see the new cell appear and execute in Jupyter Lab.
---
## ⚙️ Configuration — YAML (Developers)
This tool ships with YAML configs under `src/mcpstack_jupyter/configuration/`:
- `env_defaults.yaml` — defaults for provider/URLs/IDs and a `require_tokens` flag (we keep tokens **required**).
- `tools.yaml` — the list of upstream actions we expose by default. Adjust here as upstream evolves.
- `cli_defaults.yaml` — prompt labels and default output filename for the CLI.
You can tweak those YAML files to change defaults globally without touching code.
Tokens remain **required** and are enforced upfront by MCPStack when building the tool.
---
## 📖 Programmatic API
Use the `Jupyter` tool class directly in a pipeline.
Tokens are taken from the environment (the pipeline config or your process env):
```python
import os
from mcpstack_jupyter.tools.jupyter.jupyter import Jupyter
from MCPStack.stack import MCPStackCore
# Provide tokens via environment (same token for both is fine)
# On the long term we could think passing a StackConfig to the Jupyter tool instance, with all the necessary env vars. Open An Issue.
os.environ["DOCUMENT_TOKEN"] = "1117bf468693444a5608e882ab3b55d511f354a175a0df02"
os.environ["RUNTIME_TOKEN"] = "1117bf468693444a5608e882ab3b55d511f354a175a0df02"
pipeline = (
MCPStackCore()
.with_tool(Jupyter(include=None)) # or provide a subset of actions of interest.
# Add more tools as needed, e.g., MIMIC, etc.
# .with_tool(MIMIC(...))
.build(type="fastmcp", save_path="my_jupyter_pipeline.json")
.run()
)
```
>[!NOTE]
> Common upstream actions you can expose (see `configuration/tools.yaml`):
>
> - `append_markdown_cell`,
> - `insert_markdown_cell`,
> - `overwrite_cell_source`,
> - `delete_cell`
> - `append_execute_code_cell`,
> - `insert_execute_code_cell`
> - `execute_cell_with_progress`,
> - `execute_cell_simple_timeout`,
> - `execute_cell_streaming`
> - `read_cell`,
> - `read_all_cells`,
> - `get_notebook_info`
---
## 🧰 Troubleshooting
- **403 Forbidden / `_xsrf` missing / cannot create kernels**
Ensure you ran Jupyter with a token and that your `ToolConfig` provides **both** `DOCUMENT_TOKEN` and `RUNTIME_TOKEN`.
In most setups it’s the same token.
- **404 on `notebook.ipynb`**
Update `--document-id` to the actual notebook path relative to Jupyter’s working directory (e.g., `Untitled.ipynb` or `notebooks/analysis.ipynb`).
- **Nothing happens in Lab**
Prefer `http://127.0.0.1:8888` over `http://localhost:8888`.
Confirm your pipeline is running and that the tool is listed in `mcpstack list-tools`.
---
## 🤝 Upstream Compatibility & Support
As noted, this is a **lightweight wrapper** over the upstream Jupyter MCP Server
(`github.com/datalayer/jupyter-mcp-server`). If the upstream API changes,
we’ll happily track it — **please open an issue** with details of the version and failing action.
See more in [the official Jupyter MCP Server documentation](https://jupyter-mcp-server.datalayer.tech/).
---
## 📽️ Video Demo
<video src="https://github.com/user-attachments/assets/0e1adc61-a0fa-47e0-8c71-bc96a227b68c" width="320" height="240" controls></video>
## 🔐 License
MIT — see **[LICENSE](LICENSE)**.
Raw data
{
"_id": null,
"home_page": null,
"name": "mcpstack-jupyter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, mcpstack, mcpPipeline, tool, template",
"author": null,
"author_email": "Provost Simon <s.g.provost@kent.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/39/1a/ed520301d8210e0d876936f50dbbbec01111a14e0606839f17ef07b4e043/mcpstack_jupyter-0.0.2.tar.gz",
"platform": null,
"description": "<!--suppress HtmlDeprecatedAttribute -->\n<div align=\"center\">\n <h1 align=\"center\">\n <br>\n <a href=\"#\"><img src=\"assets/COVER.png\" alt=\"MCPStack Tool\" width=\"100%\"></a>\n <br>\n MCPStack Jupyter MCP\n <br>\n </h1>\n <h4 align=\"center\">Operate Jupyter Notebooks from your favourite LLM</h4>\n</div>\n\n<div align=\"center\">\n\n<a href=\"https://pre-commit.com/\">\n <img alt=\"pre-commit\" src=\"https://img.shields.io/badge/pre--commit-enabled-1f6feb?style=for-the-badge&logo=pre-commit\">\n</a>\n<img alt=\"ruff\" src=\"https://img.shields.io/badge/Ruff-lint%2Fformat-9C27B0?style=for-the-badge&logo=ruff&logoColor=white\">\n<img alt=\"python\" src=\"https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white\">\n<img alt=\"pytest coverage\" src=\"https://img.shields.io/badge/Coverage-66%25-brightgreen?style=for-the-badge&logo=pytest\">\n<img alt=\"license\" src=\"https://img.shields.io/badge/License-MIT-success?style=for-the-badge\">\n\n</div>\n\n> [!IMPORTANT]\n> If you haven\u2019t visited the MCPStack main orchestrator repository yet, please start\n> there: **[MCPStack](https://github.com/MCP-Pipeline/MCPStack)**\n\n## \ud83d\udca1 About The MCPStack Jupyter Tool\n\nThis repository provides an **MCPStack tool that wraps the official Python Jupyter MCP Server** \u2014 it is **not** a novel MCP by itself.\n\n- Upstream project: [datalayer/jupyter-mcp-server](https://github.com/datalayer/jupyter-mcp-server)\n- We **reuse their MCP actions** and surface them through **MCPStack**.\n- As the upstream evolves, **some actions / endpoints may deprecate**. Our wrapper is intentionally lightweight, so updating to new upstream versions should be straightforward.\n If you hit an incompatibility, **please open an issue** and we\u2019ll track an update to align with the Jupyter MCP Server.\n\n### What is MCPStack, in layman\u2019s terms?\n\nThe **Model Context Protocol (MCP)** standardises how tools talk to LLMs.\n`MCPStack` lets you **stack multiple MCP tools together** into a pipeline and expose them to an LLM host (e.g., Claude Desktop).\n\nThink **scikit-learn pipelines, but for LLM tooling**:\n- In scikit-learn: you chain `preprocessors` \u2192 `transformers` \u2192 `estimators`.\n- In MCPStack: you chain multiple MCP tools (Jupyter, MIMIC, \u2026) and the LLM can use all of them during a conversation.\n\n---\n\n## Installation\n\nThe tool is distributed as a standard Python package. Thanks to entry points, MCPStack will auto-discover it.\n\n### Via `uv` (recommended)\n\n```bash\nuv add mcpstack-jupyter\n```\n\n### Via `pip`\n\n```bash\npip install mcpstack-jupyter\n```\n\n### (Dev) Pre-commit hooks\n\n```bash\nuv run pre-commit install\n# or: pre-commit install\n```\n\n---\n\n## \ud83d\udd0c Using With MCPStack\n\nThis tool declares entry points so MCPStack can see it automatically:\n\n```toml\n[project.entry-points.\"mcpstack.tools\"]\njupyter = \"mcpstack_jupyter.tools.jupyter.jupyter:Jupyter\"\n\n[project.entry-points.\"mcpstack.tool_clis\"]\njupyter = \"mcpstack_jupyter.tools.jupyter.cli:JupyterCLI.get_app\"\n```\n\n### 1) Run Jupyter with a Token\n\nYou **must** run a Jupyter Server/Lab **with a token** (the same token will be used by both the document and runtime APIs).\n\n```bash\nuv run jupyter lab \\\n --port 8888 \\\n --IdentityProvider.token MY_TOKEN \\\n --ip 0.0.0.0\n\n# MY_TOKEN can for instance be: 1117bf468693444a5608e882ab3b55d511f354a175a0df02\n```\n\n> [!NOTE]\n> Docs reference: https://jupyter-mcp-server.datalayer.tech/jupyter/\n\nMake sure to have a notebook open in Jupyter lab, e.g., `notebook.ipynb` or whatever you have defined in the configuration.\n\n### 2) Configure the Jupyter tool (set the token)\n\nUse the tool\u2019s CLI to create a small `MCPStack ToolConfig` JSON. **At minimum pass `--token`**:\n\n```bash\nuv run mcpstack tools jupyter configure \\\n --token MY_TOKEN \\\n --output jupyter_config.json\n\n# MY_TOKEN can for instance be: 1117bf468693444a5608e882ab3b55d511f354a1750df02 (must match the Jupyter server token)\n```\n\nThe CLI has sensible defaults:\n\n- `DOCUMENT_URL`: `http://127.0.0.1:8888`\n- `DOCUMENT_ID`: `notebook.ipynb` <-- Feel free to change this to any of your notebooks.\n- `RUNTIME_URL`: defaults to `DOCUMENT_URL`\n\nYou can override those if needed:\n\n```bash\nuv run mcpstack tools jupyter configure \\\n --document-url http://127.0.0.1:8888 \\\n --document-id Untitled.ipynb \\\n --runtime-url http://127.0.0.1:8888 \\\n --token 1117bf468693444a5608e882ab3b55d511f354a1750df02 \\\n --output jupyter_config.json\n```\n\n### 3) Compose a pipeline\n\nCreate a new pipeline (or append to an existing one) and include your Jupyter ToolConfig:\n\n```bash\n# New pipeline\nuv run mcpstack pipeline jupyter --new-pipeline my_pipeline.json --tool-config jupyter_config.json\n\n# Or append to an existing pipeline\nuv run mcpstack pipeline jupyter --to-pipeline my_pipeline.json --tool-config jupyter_config.json\n```\n\n### 4) Run it inside Claude Desktop (or your host)\n\n```bash\nuv run mcpstack build --pipeline my_pipeline.json --config-type claude\n```\n\nNow ask the LLM to operate the notebook. A quick smoke test:\n\n> \u201cAppend a code cell that prints `Hello World`.\u201d\n\nIf everything\u2019s wired correctly, you should see the new cell appear and execute in Jupyter Lab.\n\n---\n\n## \u2699\ufe0f Configuration \u2014 YAML (Developers)\n\nThis tool ships with YAML configs under `src/mcpstack_jupyter/configuration/`:\n\n- `env_defaults.yaml` \u2014 defaults for provider/URLs/IDs and a `require_tokens` flag (we keep tokens **required**).\n- `tools.yaml` \u2014 the list of upstream actions we expose by default. Adjust here as upstream evolves.\n- `cli_defaults.yaml` \u2014 prompt labels and default output filename for the CLI.\n\nYou can tweak those YAML files to change defaults globally without touching code.\nTokens remain **required** and are enforced upfront by MCPStack when building the tool.\n\n---\n\n## \ud83d\udcd6 Programmatic API\n\nUse the `Jupyter` tool class directly in a pipeline.\nTokens are taken from the environment (the pipeline config or your process env):\n\n```python\nimport os\nfrom mcpstack_jupyter.tools.jupyter.jupyter import Jupyter\nfrom MCPStack.stack import MCPStackCore\n\n# Provide tokens via environment (same token for both is fine)\n# On the long term we could think passing a StackConfig to the Jupyter tool instance, with all the necessary env vars. Open An Issue.\nos.environ[\"DOCUMENT_TOKEN\"] = \"1117bf468693444a5608e882ab3b55d511f354a175a0df02\"\nos.environ[\"RUNTIME_TOKEN\"] = \"1117bf468693444a5608e882ab3b55d511f354a175a0df02\"\n\npipeline = (\n MCPStackCore()\n .with_tool(Jupyter(include=None)) # or provide a subset of actions of interest.\n # Add more tools as needed, e.g., MIMIC, etc.\n # .with_tool(MIMIC(...))\n .build(type=\"fastmcp\", save_path=\"my_jupyter_pipeline.json\")\n .run()\n)\n```\n\n>[!NOTE]\n> Common upstream actions you can expose (see `configuration/tools.yaml`):\n>\n> - `append_markdown_cell`,\n> - `insert_markdown_cell`,\n> - `overwrite_cell_source`,\n> - `delete_cell`\n> - `append_execute_code_cell`,\n> - `insert_execute_code_cell`\n> - `execute_cell_with_progress`,\n> - `execute_cell_simple_timeout`,\n> - `execute_cell_streaming`\n> - `read_cell`,\n> - `read_all_cells`,\n> - `get_notebook_info`\n\n---\n\n## \ud83e\uddf0 Troubleshooting\n\n- **403 Forbidden / `_xsrf` missing / cannot create kernels**\n Ensure you ran Jupyter with a token and that your `ToolConfig` provides **both** `DOCUMENT_TOKEN` and `RUNTIME_TOKEN`.\n In most setups it\u2019s the same token.\n\n- **404 on `notebook.ipynb`**\n Update `--document-id` to the actual notebook path relative to Jupyter\u2019s working directory (e.g., `Untitled.ipynb` or `notebooks/analysis.ipynb`).\n\n- **Nothing happens in Lab**\n Prefer `http://127.0.0.1:8888` over `http://localhost:8888`.\n Confirm your pipeline is running and that the tool is listed in `mcpstack list-tools`.\n\n---\n\n## \ud83e\udd1d Upstream Compatibility & Support\n\nAs noted, this is a **lightweight wrapper** over the upstream Jupyter MCP Server\n(`github.com/datalayer/jupyter-mcp-server`). If the upstream API changes,\nwe\u2019ll happily track it \u2014 **please open an issue** with details of the version and failing action.\n\nSee more in [the official Jupyter MCP Server documentation](https://jupyter-mcp-server.datalayer.tech/).\n\n---\n\n## \ud83d\udcfd\ufe0f Video Demo\n\n<video src=\"https://github.com/user-attachments/assets/0e1adc61-a0fa-47e0-8c71-bc96a227b68c\" width=\"320\" height=\"240\" controls></video>\n\n\n## \ud83d\udd10 License\n\nMIT \u2014 see **[LICENSE](LICENSE)**.\n",
"bugtrack_url": null,
"license": null,
"summary": "MCPStack delegator for jupyter-mcp-server (Option A: reuse their tools verbatim).",
"version": "0.0.2",
"project_urls": null,
"split_keywords": [
"mcp",
" mcpstack",
" mcppipeline",
" tool",
" template"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "153c888b314b6d8a0844ef5a47f0ec49931bd701c6f6d7e1e4db7647ecd593d6",
"md5": "092a34eb2700fa08b6c4123e07ec49d4",
"sha256": "276657b8e7f3f77f14ff966bc39561fd1df0fcdc3046b32415fe8bc3eb62402d"
},
"downloads": -1,
"filename": "mcpstack_jupyter-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "092a34eb2700fa08b6c4123e07ec49d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12141,
"upload_time": "2025-08-21T12:50:12",
"upload_time_iso_8601": "2025-08-21T12:50:12.398895Z",
"url": "https://files.pythonhosted.org/packages/15/3c/888b314b6d8a0844ef5a47f0ec49931bd701c6f6d7e1e4db7647ecd593d6/mcpstack_jupyter-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "391aed520301d8210e0d876936f50dbbbec01111a14e0606839f17ef07b4e043",
"md5": "da270c935982945f70f873625b7838f5",
"sha256": "6ff03683b74976fc46ce277f298bc5da8b804976a08f2b8927adc4a1a75701f4"
},
"downloads": -1,
"filename": "mcpstack_jupyter-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "da270c935982945f70f873625b7838f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 14102,
"upload_time": "2025-08-21T12:50:13",
"upload_time_iso_8601": "2025-08-21T12:50:13.493585Z",
"url": "https://files.pythonhosted.org/packages/39/1a/ed520301d8210e0d876936f50dbbbec01111a14e0606839f17ef07b4e043/mcpstack_jupyter-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 12:50:13",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mcpstack-jupyter"
}
