{"id":28431750,"url":"https://github.com/block/mcp-jupyter","last_synced_at":"2025-07-05T00:31:29.638Z","repository":{"id":290820592,"uuid":"974525346","full_name":"block/mcp-jupyter","owner":"block","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-23T21:37:22.000Z","size":653,"stargazers_count":11,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-23T22:35:52.199Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/block.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-28T23:11:22.000Z","updated_at":"2025-06-09T19:24:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"90768b56-520f-459f-bab0-551e82dfc01b","html_url":"https://github.com/block/mcp-jupyter","commit_stats":null,"previous_names":["block/mcp-jupyter"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/block/mcp-jupyter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fmcp-jupyter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fmcp-jupyter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fmcp-jupyter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fmcp-jupyter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/block","download_url":"https://codeload.github.com/block/mcp-jupyter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fmcp-jupyter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261578087,"owners_count":23179774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-05T16:08:17.117Z","updated_at":"2025-07-05T00:31:29.626Z","avatar_url":"https://github.com/block.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jupyter MCP Server\n\nJupyter MCP Server allows you to use tools like [Goose](https://block.github.io/goose/) or Cursor to pair with you in a JupyterLab notebook where the state of your variables, etc is preserved by the JupyterLab Kernel.  The fact that state is preserved is the key to this because it allows to to pair with the Agent in a notebook, where for example if a package is not installed it will see the error and install it for you.   You as the user can then do some data exploration and then hand off to the agent at any time to pick up where you left off.\n\n## Key Features\n\n- **4 Consolidated MCP Tools** (reduced from 11):\n  - `query_notebook` - All read-only operations (view source, check server, etc.)\n  - `modify_notebook_cells` - All cell modifications (add, edit, delete cells)\n  - `execute_notebook_code` - All execution operations (run cells, install packages)\n  - `setup_notebook` - Notebook initialization and kernel connection\n- **Workflow-oriented design** optimized for AI agent collaboration\n- **State preservation** across notebook sessions\n- **Automatic parameter validation** with float-to-int conversion\n\nThis works with any client that supports MCP but will focus on using Goose for the examples.\n\n## Requirements\nYou will need [UV](https://docs.astral.sh/uv/) is required to be installed. \n\n## Installation\nThis MCP server uses stdio and can been added to client with the command `uvx mcp-jupyter`.  \n\n## Usage\n\n### Start Jupyter\nThe server expects that a server is already running on a port that is available to the client. If the environmental variable TOKEN is not set, it will default to \"BLOCK\". The server requires that jupyter-collaboration and ipykernel are installed.\n\n**Option 1: Using uv venv**\n```bash\n# Create virtual environment  \nuv venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install Jupyter dependencies\nuv pip install jupyterlab jupyter-collaboration ipykernel\n\n# Start Jupyter\njupyter lab --port 8888 --IdentityProvider.token BLOCK --ip 0.0.0.0\n```\n\n**Option 2: Using uv project**\n```bash\n# Initialize project (if you don't have one)\nuv init jupyter-workspace \u0026\u0026 cd jupyter-workspace\n\n# Install Jupyter dependencies\nuv add jupyterlab jupyter-collaboration ipykernel\n\n# Start Jupyter\nuv run jupyter lab --port 8888 --IdentityProvider.token BLOCK --ip 0.0.0.0\n```\n\n### Goose Usage\n\nHere's a demonstration of the tool in action:\n\n![MCP Jupyter Demo](demos/goose-demo.png) \n\nYou can view the Generated notebook here: [View Demo Notebook](demos/demo.ipynb)\n\n## Development\nSteps remain similar except you will need to clone this mcp-jupyter repository and use that for the server instead of the precompiled version.\n\n### MCP Server\n\n1. Clone and setup the repository:\n```bash\nmkdir ~/Development\ncd ~/Development\ngit clone https://github.com/block/mcp-jupyter.git\ncd mcp-jupyter\n\n# Sync all dependencies\nuv sync\n```\n\nUsing editable mode allows you to make changes to the server and only have you need to restart Goose, etc.\n`goose session --with-extension \"uv run --directory $(pwd) mcp-jupyter\"`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock%2Fmcp-jupyter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblock%2Fmcp-jupyter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock%2Fmcp-jupyter/lists"}