MCP Server for Claude AI Jupyter Notebook

Overview

This MCP (Model Context Protocol) server bridges a local Jupyter Notebook environment and Anthropic Claude (or other MCP-compatible models). It implements MCP endpoints so the notebook can offload intelligent tasks—code generation, code execution orchestration, data analysis, and visualization—to an LLM-driven assistant while maintaining a secure, local execution surface for running code and inspecting results.

For developers, the server is useful because it separates the LLM logic from execution context. The model can propose or modify code and request actions, and the MCP server safely executes those actions in the notebook environment (files, Python execution, plotting). That flow enables AI-assisted exploratory data analysis, reproducible code edits, and interactive visualizations while keeping data and runtime under the user’s control.

Features

• MCP-compliant API to connect Claude (or other MCP-capable models) with Jupyter
• Remote code execution service that runs Python snippets and returns stdout, stderr, and rich outputs
• File access and lightweight file browsing for datasets and notebooks
• Visualization helper that captures plots (PNG/SVG) and returns them to the model/client
• Simple authentication via API key or environment variables
• Docker-friendly and runnable locally with minimal configuration

Installation / Configuration

Clone and install dependencies, create a virtual environment, and run the server locally:

git clone https://github.com/jjsantos01/jupyter-notebook-mcp.git
cd jupyter-notebook-mcp

# Create virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the server (example)
export MCP_PORT=3000
export ANTHROPIC_API_KEY="sk-xxxx"
python server.py
# or if using ASGI:
# uvicorn main:app --reload --port $MCP_PORT

Docker example:

docker build -t jupyter-mcp .
docker run -p 3000:3000 \
  -e ANTHROPIC_API_KEY="sk-xxxx" \
  -e MCP_PORT=3000 \
  -v "$(pwd)/workspace:/workspace" \
  jupyter-mcp

Recommended environment variables

Create a .env file for convenience:

ANTHROPIC_API_KEY=sk-xxxx
MCP_PORT=3000
WORKSPACE_DIR=./workspace

Security note: only bind to 127.0.0.1 for local-only use or secure the server behind authentication when exposing to networks.

Available Tools / Resources

This server exposes a set of MCP-aligned tools (endpoints) that clients — including Jupyter extensions or custom scripts — can call.

• Session management: Create and list MCP sessions
• Code execution: Run Python snippets and return outputs, exceptions, and optional artifacts (images, files)
• File operations: List, read, write files within the configured workspace
• Plot capture: Convert matplotlib/plotly outputs into embeddable images
• Logs & history: Retrieve previous actions and execution traces

Typical (example) endpoints

• POST /mcp/session — create a new assistant session
• POST /mcp/execute — execute Python code and return structured result
• GET /mcp/files — list workspace files
• POST /mcp/files — upload or write a file
• POST /mcp/visualize — execute plotting code and return image bytes

(Exact endpoint names may vary — consult the repository source for concrete API paths.)

Use Cases

1. Interactive data exploration

   • Ask Claude to suggest a data-cleaning pipeline for a CSV in the workspace. The assistant emits Python code, the MCP server runs it, and returns cleaned DataFrame previews and summary statistics.

2. Visualization generation

   • Request a specific plot (scatter with trendline). The model provides plotting code; the MCP server executes it and returns an image that you can embed directly in a notebook.

3. Automated refactor & test-run cycle

   • Ask the assistant to refactor a function in a module. The assistant edits the file via MCP file tools, then triggers unit tests via code execution and returns pass/fail output and error traces.

4. Reproducible experiment orchestration

   • Use the MCP session to run experiments with different hyperparameters. The model generates experiment scripts, the server runs them and logs results into workspace files for later inspection.

5. Educational / pair programming

   • Students can get guidance and runnable examples: the assistant provides annotated code and the server executes it so the student can inspect results line-by-line without copy/paste.

Example: executing code from a Jupyter cell (simple POST example)

import requests, os
server = "http://localhost:3000"
payload = {"code": "import pandas as pd\nprint(pd.__version__)\n"}
r = requests.post(f"{server}/mcp/execute", json=payload)
print(r.json())  # structured output: stdout, stderr, return value, artifacts

Next steps and tips

• Review server source to map exact endpoints and payload formats to your client integration.
• Limit workspace access and prefer local-only binding when experimenting.
• Add authentication (token-based) if exposing on a shared network.
• Extend tools by implementing additional MCP-compatible actions (e.g., database queries, shell commands with strict sandboxing).

This MCP server puts an LLM-driven assistant into the loop while keeping code execution and data local, enabling secure, interactive, and reproducible AI-assisted development workflows in Jupyter.