A configurable MCP (Model Context Protocol) server extension for Jupyter Server that allows dynamic registration of Python functions as tools accessible to MCP clients from a running Jupyter Server.
This extension provides a simplified, trait-based approach to exposing Jupyter functionality through the MCP protocol. It can dynamically load and register tools from various Python packages, making them available to AI assistants and other MCP clients.
Key Features
Simplified Architecture: Direct function registration without complex abstractions
Configurable Tool Loading: Register tools via string specifications (module:function)
Automatic Tool Discovery: Python packages can expose tools via entrypoints
Jupyter Integration: Seamless integration with Jupyter Server extension system
Streamable HTTP Transport: FastMCP-based HTTP server with proper MCP protocol support
Stdio Proxy: Stable jupyter-server-mcp-proxy / python -m jupyter_server_mcp.proxy entry point that auto-discovers the running Jupyter MCP server — client configuration stays the same even if the port changes, and it is launchable via uvx from outside the Jupyter environment
Multi-Instance Ready: Set mcp_port = 0 to ask the OS for a free ephemeral port, so multiple Jupyter servers can run in parallel; the stdio proxy auto-discovers whichever port was chosen
Traitlets Configuration: Full configuration support through Jupyter's traitlets system
Installation
Install jupyter-server-mcp into the same environment as Jupyter Server or JupyterLab.
# If conda-forge is not already configured for the workspace
pixi project channel add conda-forge
pixi add jupyter-server-mcp
Quick Start
1. Basic Configuration
Create a jupyter_config.py file:
c = get_config()
# Basic MCP server settings
c.MCPExtensionApp.mcp_name = "My Jupyter MCP Server"
# The MCP server listens on port 3001 by default. Override it with:
# c.MCPExtensionApp.mcp_port = 8080
# Set to 0 to let the OS pick a free port — useful when running multiple
# Jupyter servers side by side. The stdio proxy (below) auto-discovers the
# chosen port, so clients do not need to be reconfigured.
# c.MCPExtensionApp.mcp_port = 0
# Register tools from existing packages
c.MCPExtensionApp.mcp_tools = [
# Standard library tools
"os:getcwd",
"json:dumps",
"time:time",
# Jupyter AI Tools - Notebook operations
"jupyter_ai_tools.toolkits.notebook:read_notebook",
"jupyter_ai_tools.toolkits.notebook:edit_cell",
# JupyterLab Commands Toolkit
"jupyterlab_commands_toolkit.tools:list_all_commands",
"jupyterlab_commands_toolkit.tools:execute_command",
]
2. Start Jupyter Server
jupyter lab --config=jupyter_config.py
By default, the MCP server listens on port 3001. If that port is already in
use — for example when a second Jupyter server is already running — startup
fails with a clear error instead of silently choosing another port. To run
multiple Jupyter servers side-by-side, set c.MCPExtensionApp.mcp_port = 0 so
the OS assigns a free port. The stdio proxy (see below) auto-discovers
whichever port was chosen, so client configuration does not need to change.
Any trait can also be set on the command line:
jupyter lab --MCPExtensionApp.mcp_port=8080
3. CLI MCP Client Configuration
There are two supported ways to wire an MCP client to this extension:
Stdio proxy (recommended) — the client launches a small stdio proxy (jupyter-server-mcp-proxy or python -m jupyter_server_mcp.proxy), which auto-discovers the running Jupyter MCP server and bridges stdio to its HTTP endpoint. This keeps working unchanged when multiple Jupyter servers run side-by-side or when mcp_port = 0 picks a different port each run.
Direct HTTP — point the client at http://localhost:3001/mcp (or whichever port you configured). Works well when you run a single Jupyter server on a stable port.
The stdio proxy connects to the Jupyter server whose root directory is the most specific ancestor of the MCP client's current working directory, so a coding agent started in a project folder talks to the Jupyter server that serves that folder. The rule also applies when only one server is running: if no server's root directory contains the working directory, or if several tie, the proxy refuses to guess and exits with an error listing the running servers. Start the agent inside a folder a server serves, start a Jupyter server in that folder, or pick a server explicitly with --url or by setting JUPYTER_SERVER_MCP_URL.
The list below is intentionally curated rather than exhaustive and focuses on terminal-based coding agents.
For a broader, community-maintained directory of MCP-compatible clients, see the MCP client directory: https://modelcontextprotocol.io/clients.
Option A — Stdio proxy (recommended)
The proxy can be launched in two ways:
uvx — ideal for MCP clients that are not installed inside the same
Python environment as Jupyter. uv installs
jupyter-server-mcp into a cached, ephemeral environment and runs its
jupyter-server-mcp-proxy console script. The runtime info file the
extension writes is stored in the per-user Jupyter runtime directory, so
auto-discovery works across environments.
python -m jupyter_server_mcp.proxy — use when the client is
already running in an environment that has jupyter-server-mcp
installed.
The examples below show the uvx form. Swap in the python -m form by
replacing "command": "uvx", "args": ["--from", "jupyter-server-mcp", "jupyter-server-mcp-proxy"]
with "command": "python", "args": ["-m", "jupyter_server_mcp.proxy"].
Pin to a specific version with --from jupyter-server-mcp==X.Y.Z when you
need to match the server side exactly.
The proxy accepts a few optional arguments (append them to args):
--url URL — bypass auto-discovery and connect to an explicit MCP endpoint
--runtime-dir DIR — look in a specific Jupyter runtime directory
--cwd DIR — match servers against this directory instead of the current working directory
JUPYTER_SERVER_MCP_URL is equivalent to --url and takes precedence over discovery when set.
Option B — Direct HTTP
The extension exposes a FastMCP streamable HTTP endpoint at
http://localhost:3001/mcp by default. Override the port with
c.MCPExtensionApp.mcp_port if you need a different one; replace 3001
below with whatever you chose. If a client asks for a transport type,
pick HTTP or Streamable HTTP.
Note: Direct HTTP requires a fixed, known port. If you set
c.MCPExtensionApp.mcp_port = 0 for multi-instance support, use the
stdio proxy instead — the ephemeral port is not suitable as a stable URL.
OpenCode
Use opencode mcp add, or add the following to opencode.json or ~/.config/opencode/opencode.json:
# Option 1: Define as a list
TOOLS = [
"my_package.operations:create_file",
"my_package.operations:delete_file",
]
# Option 2: Define as a function
def get_tools():
return [
"my_package.operations:create_file",
"my_package.operations:delete_file",
]
Tools from entrypoints are discovered automatically when the extension starts. To disable automatic discovery:
c.MCPExtensionApp.use_tool_discovery = False
Middleware
FastMCP middleware runs around every request to the MCP server, for example to read request headers before a tool call. Middleware is added the same two ways as tools. Each specification names a factory called without arguments that returns the middleware; a Middleware subclass works as is.
c = get_config()
# The MCP server defaults to port 3001. Override it with:
# c.MCPExtensionApp.mcp_port = 8080
# Or set to 0 to let the OS pick a free port (requires the stdio proxy).
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Sorular
Jupyter nasıl kurulur?
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
Jupyter için API anahtarı gerekiyor mu?
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
Jupyter hangi aktarımı kullanıyor?
Jupyter yerel olarak stdio üzerinden çalışır.
Jupyter en son ne zaman kontrol edildi?
Son kontrol: 2026-10-27. An MCP interface/extension for Jupyter Server