Skip to main content

As a Standalone Server

1. Start JupyterLab​

Environment setup​

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.

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

JupyterLab start​

Then, start JupyterLab with the following command.

jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN

You can also run make jupyterlab if you cloned the repository.

note

If you wish to start the Jupyter MCP server using docker, add --ip 0.0.0.0 to the jupyter lab command to allow the MCP Server running in a Docker container to access your local JupyterLab.

info

For JupyterHub:

  • Set the environment variable JUPYTERHUB_ALLOW_TOKEN_IN_URL=1 in the single-user environment.
  • Ensure your API token (MY_TOKEN) is created with access:servers scope in the Hub.

2. Start Jupyter MCP Server​

The server runs on port 4040 and provides a streamable HTTP endpoint at http://localhost:4040/mcp.

Using Python​

Install and start the server:

pip install jupyter-mcp-server
jupyter-mcp-server start \
  --transport streamable-http \
  --jupyter-url http://localhost:8888 \
  --jupyter-token MY_TOKEN \
  --port 4040

Using Docker​

MacOS/Windows:

docker run \
  -e JUPYTER_URL="http://host.docker.internal:8888" \
  -e JUPYTER_TOKEN="MY_TOKEN" \
  -p 4040:4040 \
  datalayer/jupyter-mcp-server:latest \
  --transport streamable-http

Linux:

docker run \
  --network=host \
  -e JUPYTER_URL="http://localhost:8888" \
  -e JUPYTER_TOKEN="MY_TOKEN" \
  -p 4040:4040 \
  datalayer/jupyter-mcp-server:latest \
  --transport streamable-http

For advanced configuration options, see the server configuration guide.

3. Configure your MCP Client​

Use the following configuration to connect to the running server:

{
  "mcpServers": {
    "jupyter": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:4040/mcp"]
    }
  }
}

Troubleshooting​

Common Issues​

Connection refused:

  • Verify the MCP server is running: curl http://localhost:4040/mcp
  • Check that port 4040 is not blocked by firewall
  • Ensure Docker port mapping is correct (-p 4040:4040)

Authentication errors:

  • Verify JUPYTER_TOKEN matches your Jupyter server token
  • Check Jupyter server is accessible from MCP server

For detailed configuration and troubleshooting, see the configuration guide.