# MCP Notebook Data
An MCP server that lets AI agents run a live Jupyter notebook session creating code and markdown cells, managing Python packages, and connecting to data sources. Unlike MCP servers that fetch data and hand it directly to a language model, `MCP Notebook Data` loads query results into the notebook as pandas DataFrames, so agents analyze with code, explain in markdown, and visualize patterns—all within a single notebook session.
---
## Why
Typical `data MCP servers` fetch data on the server side and pass results straight to an LLM. That clashes with:
* Large datasets (pressure on attention and context-window budgets).
* Data analysis as code (you want imports, transforms, plots, tests).
* Reproducibility (keep reasoning and analysis steps that can be re-run and audited).
> This project flips that model: use the MCP session to operate a Jupyter notebook and materialize data as pandas DataFrames inside the kernel. The agent continues in Python—explore, transform, visualize—without dumping big payloads into prompts.
---
## Core ideas
* **One live notebook session** per MCP server instance (kernel + document).
* **Notebook tools**: add markdown, run code, ensure packages.
* **Data connector tools**: initialize a client inside the kernel, run queries there, and assign `df_<id>` for continued work in Python.
* **Data stays in the kernel**: the server returns only compact JSON metadata (e.g., schema, small sample) to guide the agent.
---
## Tool Included
### Notebook tools (always enabled)
* `notebook.markdown.add(content)`: Append a markdown cell. Returns index, status, timing.
* `notebook.code.run(content)`: Append a Python code cell and execute it. Returns stdout, stderr, rich outputs, status.
* `notebook.packages.add([packages])`: Best-effort ensure pip packages inside the kernel (idempotent).
### Data connector toolsets (opt-in)
#### PostgreSQL tools
* `db.postgresql.schema.list_tables(schema_name=None, include_matviews=False)`: Tables/views (and materialized views if requested).
* `db.postgresql.schema.list_columns(schema_name, table)`: Column metadata for a table.
* `db.postgresql.schema.tree(limit_per_schema=100)`: Compact schema → tables mapping (filters system schemas).
* `db.postgresql.query.to_df(raw_sql, limit=50)`: Executes SQL in the notebook kernel, assigns a DataFrame like `df_ab12cd`, shows a short preview in the notebook, and returns JSON metadata (schema, row/col counts, data sample). A single shared client (`__JAT_PG__`) is reused per kernel.
> Connector drivers (e.g., psycopg) are installed into the notebook kernel on demand, not in the MCP server process.
---
## Installation
### From PyPI
The easiest way is to install the package directly from PyPI:
```bash
# With uv (recommended)
uv pip install mcp-notebook-data
# Or with pip
pip install mcp-notebook-data
```
To enable a specific connector, install with extras. For example, PostgreSQL:
```bash
uv pip install "mcp-notebook-data[postgresql]"
# or
pip install "mcp-notebook-data[postgresql]"
```
### From Source
If you want to work with the latest code from GitHub:
```bash
git clone https://github.com/Cyb3rWard0g/mcp-notebook-data.git
cd mcp-notebook-data
# Create a virtual environment
uv venv .venv
source .venv/bin/activate
# Install in editable/dev mode
uv pip install -e ".[dev]"
# or
pip install -e ".[dev]"
```
You can still add extras here, e.g.:
```bash
uv pip install -e ".[dev,postgresql]"
```
---
## Configure Server
Set environment to point at your Jupyter and (optionally) enable data toolsets:
```bash
# Jupyter (server mode)
export MCP_JUPYTER_SESSION_MODE=server # or "local"
export MCP_JUPYTER_BASE_URL=http://localhost:8888 # required in server mode
export MCP_JUPYTER_TOKEN=<your-jupyter-token> # required in server mode
export MCP_JUPYTER_KERNEL_NAME=python3 # default
export MCP_JUPYTER_NOTEBOOK_PATH=mcp_demo.ipynb # optional; auto name if unset
# Toolsets (comma-separated; notebook is always on)
export MCP_JUPYTER_TOOLSETS=postgresql # enable Postgres tools
# For Postgres toolset (read by the notebook kernel)
export PG_DSN=postgresql://user:pass@host:5432/db?sslmode=disable
# or POSTGRES_DSN / DATABASE_URL
```
## Run Server
### Stdio (recommended for desktop MCP clients):
```bash
mcp-notebook-data --transport stdio
```
### SSE:
```bash
mcp-notebook-data --transport sse --host 0.0.0.0 --port 8000
```
### Streamable HTTP:
```bash
mcp-notebook-data --transport streamable-http --host 0.0.0.0 --port 8000
```
### With uvx:
```bash
uvx mcp-notebook-data --transport stdio
```
Example client config (stdio)
```json
{
"mcpServers": {
"notebook-data": {
"command": "uvx",
"args": ["mcp-notebook-data", "--transport", "stdio"],
"env": {
"MCP_JUPYTER_SESSION_MODE": "server",
"MCP_JUPYTER_BASE_URL": "http://localhost:8888",
"MCP_JUPYTER_TOKEN": "<your-token>",
"MCP_JUPYTER_KERNEL_NAME": "python3",
"MCP_JUPYTER_NOTEBOOK_PATH": "mcp_session.ipynb",
"MCP_JUPYTER_TOOLSETS": "postgresql"
}
}
}
}
```
---
## Quickstarts
### PostgreSQL Data Tools
See [quickstarts/postgresql/](quickstarts/postgresql/README.md) for a self-contained example that:
* spins up Postgres with sample data (docker compose),
* launches the MCP server with the Postgres toolset,
* drives the notebook through an agent using these tools.
## Release Process
To publish a new release to PyPI:
0. Install dev dependencies
```sh
uv pip install -e ".[dev]"
```
1. Ensure all changes are committed and tests pass:
```sh
uv run pytest tests/
```
2. Create and push an **annotated tag** for the release:
```sh
git tag -a v0.1.0 -m "Release 0.1.0"
git push origin v0.1.0
```
3. Checkout the tag to ensure you are building exactly from it:
```sh
git checkout v0.1.0
```
4. Clean old build artifacts:
```sh
rm -rf dist
rm -rf build
rm -rf src/*.egg-info
```
5. Upgrade build and upload tools:
```sh
uv pip install --upgrade build twine packaging setuptools wheel setuptools_scm
```
6. Build the package:
```sh
uv run python -m build
```
7. (Optional) Check metadata:
```sh
uv run twine check dist/*
```
8. Upload to PyPI:
```sh
uv run twine upload dist/*
```
**Notes:**
* Twine ≥ 6 and packaging ≥ 24.2 are required for modern metadata support.
* Always build from the tag (`git checkout vX.Y.Z`) so setuptools_scm resolves the exact version.
* `git checkout v0.1.0` puts you in detached HEAD mode; that’s normal. When done, return to your branch with:
```sh
git switch -
```
* If you’re building in CI, make sure tags are fetched:
```sh
git fetch --tags --force --prune
git fetch --unshallow || true
```
---
## Running Tests
```bash
uv venv .venv
source .venv/bin/activate
# install your package in editable mode with dev tools
uv pip install -e ".[dev]"
# ruff: lint + fix
ruff check src tests --fix
# black: format
black src tests
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-notebook-data",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "MCP, Jupyter, notebooks, agents, data, server",
"author": null,
"author_email": "Roberto Rodriguez <9653181+Cyb3rWard0g@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/d3/b5/e5801d4324adf81ef2acf420de6006f449de725bf099007cb449828ca4c6/mcp_notebook_data-0.1.1.tar.gz",
"platform": null,
"description": "# MCP Notebook Data\n\nAn MCP server that lets AI agents run a live Jupyter notebook session creating code and markdown cells, managing Python packages, and connecting to data sources. Unlike MCP servers that fetch data and hand it directly to a language model, `MCP Notebook Data` loads query results into the notebook as pandas DataFrames, so agents analyze with code, explain in markdown, and visualize patterns\u2014all within a single notebook session.\n\n---\n\n## Why\n\nTypical `data MCP servers` fetch data on the server side and pass results straight to an LLM. That clashes with:\n\n* Large datasets (pressure on attention and context-window budgets).\n* Data analysis as code (you want imports, transforms, plots, tests).\n* Reproducibility (keep reasoning and analysis steps that can be re-run and audited).\n\n> This project flips that model: use the MCP session to operate a Jupyter notebook and materialize data as pandas DataFrames inside the kernel. The agent continues in Python\u2014explore, transform, visualize\u2014without dumping big payloads into prompts.\n\n---\n\n## Core ideas\n\n* **One live notebook session** per MCP server instance (kernel + document).\n* **Notebook tools**: add markdown, run code, ensure packages.\n* **Data connector tools**: initialize a client inside the kernel, run queries there, and assign `df_<id>` for continued work in Python.\n* **Data stays in the kernel**: the server returns only compact JSON metadata (e.g., schema, small sample) to guide the agent.\n\n---\n\n## Tool Included\n\n### Notebook tools (always enabled)\n\n* `notebook.markdown.add(content)`: Append a markdown cell. Returns index, status, timing.\n* `notebook.code.run(content)`: Append a Python code cell and execute it. Returns stdout, stderr, rich outputs, status.\n* `notebook.packages.add([packages])`: Best-effort ensure pip packages inside the kernel (idempotent).\n\n### Data connector toolsets (opt-in)\n\n#### PostgreSQL tools\n\n* `db.postgresql.schema.list_tables(schema_name=None, include_matviews=False)`: Tables/views (and materialized views if requested).\n* `db.postgresql.schema.list_columns(schema_name, table)`: Column metadata for a table.\n* `db.postgresql.schema.tree(limit_per_schema=100)`: Compact schema \u2192 tables mapping (filters system schemas).\n* `db.postgresql.query.to_df(raw_sql, limit=50)`: Executes SQL in the notebook kernel, assigns a DataFrame like `df_ab12cd`, shows a short preview in the notebook, and returns JSON metadata (schema, row/col counts, data sample). A single shared client (`__JAT_PG__`) is reused per kernel.\n\n> Connector drivers (e.g., psycopg) are installed into the notebook kernel on demand, not in the MCP server process.\n\n---\n\n## Installation\n\n### From PyPI\n\nThe easiest way is to install the package directly from PyPI:\n\n```bash\n# With uv (recommended)\nuv pip install mcp-notebook-data\n\n# Or with pip\npip install mcp-notebook-data\n```\n\nTo enable a specific connector, install with extras. For example, PostgreSQL:\n\n```bash\nuv pip install \"mcp-notebook-data[postgresql]\"\n# or\npip install \"mcp-notebook-data[postgresql]\"\n```\n\n### From Source\n\nIf you want to work with the latest code from GitHub:\n\n```bash\ngit clone https://github.com/Cyb3rWard0g/mcp-notebook-data.git\ncd mcp-notebook-data\n\n# Create a virtual environment\nuv venv .venv\nsource .venv/bin/activate\n\n# Install in editable/dev mode\nuv pip install -e \".[dev]\"\n# or\npip install -e \".[dev]\"\n```\n\nYou can still add extras here, e.g.:\n\n```bash\nuv pip install -e \".[dev,postgresql]\"\n```\n\n---\n\n## Configure Server\n\nSet environment to point at your Jupyter and (optionally) enable data toolsets:\n\n```bash\n# Jupyter (server mode)\nexport MCP_JUPYTER_SESSION_MODE=server # or \"local\"\nexport MCP_JUPYTER_BASE_URL=http://localhost:8888 # required in server mode\nexport MCP_JUPYTER_TOKEN=<your-jupyter-token> # required in server mode\nexport MCP_JUPYTER_KERNEL_NAME=python3 # default\nexport MCP_JUPYTER_NOTEBOOK_PATH=mcp_demo.ipynb # optional; auto name if unset\n\n# Toolsets (comma-separated; notebook is always on)\nexport MCP_JUPYTER_TOOLSETS=postgresql # enable Postgres tools\n\n# For Postgres toolset (read by the notebook kernel)\nexport PG_DSN=postgresql://user:pass@host:5432/db?sslmode=disable\n# or POSTGRES_DSN / DATABASE_URL\n```\n\n## Run Server\n\n### Stdio (recommended for desktop MCP clients):\n\n```bash\nmcp-notebook-data --transport stdio\n```\n\n### SSE:\n\n```bash\nmcp-notebook-data --transport sse --host 0.0.0.0 --port 8000\n```\n\n### Streamable HTTP:\n\n```bash\nmcp-notebook-data --transport streamable-http --host 0.0.0.0 --port 8000\n```\n\n### With uvx:\n\n```bash\nuvx mcp-notebook-data --transport stdio\n```\n\nExample client config (stdio)\n\n```json\n{\n \"mcpServers\": {\n \"notebook-data\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-notebook-data\", \"--transport\", \"stdio\"],\n \"env\": {\n \"MCP_JUPYTER_SESSION_MODE\": \"server\",\n \"MCP_JUPYTER_BASE_URL\": \"http://localhost:8888\",\n \"MCP_JUPYTER_TOKEN\": \"<your-token>\",\n \"MCP_JUPYTER_KERNEL_NAME\": \"python3\",\n \"MCP_JUPYTER_NOTEBOOK_PATH\": \"mcp_session.ipynb\",\n \"MCP_JUPYTER_TOOLSETS\": \"postgresql\"\n }\n }\n }\n}\n```\n\n---\n\n## Quickstarts\n\n### PostgreSQL Data Tools\n\nSee [quickstarts/postgresql/](quickstarts/postgresql/README.md) for a self-contained example that:\n\n* spins up Postgres with sample data (docker compose),\n* launches the MCP server with the Postgres toolset,\n* drives the notebook through an agent using these tools.\n\n## Release Process\n\nTo publish a new release to PyPI:\n\n0. Install dev dependencies\n ```sh\n uv pip install -e \".[dev]\"\n ``` \n1. Ensure all changes are committed and tests pass:\n ```sh\n uv run pytest tests/\n ```\n2. Create and push an **annotated tag** for the release:\n ```sh\n git tag -a v0.1.0 -m \"Release 0.1.0\"\n git push origin v0.1.0\n ```\n3. Checkout the tag to ensure you are building exactly from it:\n ```sh\n git checkout v0.1.0\n ```\n4. Clean old build artifacts:\n ```sh\n rm -rf dist\n rm -rf build\n rm -rf src/*.egg-info\n ```\n5. Upgrade build and upload tools:\n ```sh\n uv pip install --upgrade build twine packaging setuptools wheel setuptools_scm\n ```\n6. Build the package:\n ```sh\n uv run python -m build\n ```\n7. (Optional) Check metadata:\n ```sh\n uv run twine check dist/*\n ```\n8. Upload to PyPI:\n ```sh\n uv run twine upload dist/*\n ```\n\n**Notes:**\n* Twine \u2265 6 and packaging \u2265 24.2 are required for modern metadata support.\n* Always build from the tag (`git checkout vX.Y.Z`) so setuptools_scm resolves the exact version.\n* `git checkout v0.1.0` puts you in detached HEAD mode; that\u2019s normal. When done, return to your branch with:\n ```sh\n git switch -\n ```\n* If you\u2019re building in CI, make sure tags are fetched:\n ```sh\n git fetch --tags --force --prune\n git fetch --unshallow || true\n ```\n\n---\n\n## Running Tests\n\n```bash\nuv venv .venv\nsource .venv/bin/activate\n\n# install your package in editable mode with dev tools\nuv pip install -e \".[dev]\"\n\n# ruff: lint + fix\nruff check src tests --fix\n\n# black: format\nblack src tests\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Modular notebook data server (MCP) with pluggable tools for Jupyter kernels",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/Cyb3rWard0g/mcp-notebook-data",
"Issues": "https://github.com/Cyb3rWard0g/mcp-notebook-data/issues",
"Repository": "https://github.com/Cyb3rWard0g/mcp-notebook-data"
},
"split_keywords": [
"mcp",
" jupyter",
" notebooks",
" agents",
" data",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d9338bb6b3389db75691b7ae88841ba8f02e92bf8e7a1893cbdfdb9429ff26c4",
"md5": "7f863e8ff70e1ecfa21f4bac65c61e48",
"sha256": "43755209e0dcd45e96a57256e0a971f3116b081c35f06a159ee83c5cb8d3c6d2"
},
"downloads": -1,
"filename": "mcp_notebook_data-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f863e8ff70e1ecfa21f4bac65c61e48",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 21580,
"upload_time": "2025-10-14T23:08:35",
"upload_time_iso_8601": "2025-10-14T23:08:35.006576Z",
"url": "https://files.pythonhosted.org/packages/d9/33/8bb6b3389db75691b7ae88841ba8f02e92bf8e7a1893cbdfdb9429ff26c4/mcp_notebook_data-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d3b5e5801d4324adf81ef2acf420de6006f449de725bf099007cb449828ca4c6",
"md5": "324a553cd30372a2d655a225803470f7",
"sha256": "6dd2b27c01527a59f461c0deda580379b1f3a36c5e68576cf674fd99259c6808"
},
"downloads": -1,
"filename": "mcp_notebook_data-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "324a553cd30372a2d655a225803470f7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 195244,
"upload_time": "2025-10-14T23:08:36",
"upload_time_iso_8601": "2025-10-14T23:08:36.198759Z",
"url": "https://files.pythonhosted.org/packages/d3/b5/e5801d4324adf81ef2acf420de6006f449de725bf099007cb449828ca4c6/mcp_notebook_data-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 23:08:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Cyb3rWard0g",
"github_project": "mcp-notebook-data",
"github_not_found": true,
"lcname": "mcp-notebook-data"
}
JSON
