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
tip

To confirm your environment is correctly configured:

  1. Open a notebook in JupyterLab
  2. Type some content in any cell (code or markdown)
  3. Observe the tab indicator: you should see an "×" appear next to the notebook name, indicating unsaved changes
  4. Wait a few seconds—the "×" should automatically change to a "●" without manually saving

This automatic saving behavior confirms that the real-time collaboration features are working properly, which is essential for MCP server integration.

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.