As a data scientist, your Jupyter Notebook is your castle. But what happens when you want an external program to control it?

Maybe you want an AI agent (like Gemini or Claude) to add new cells, or a script to automatically clear all outputs before a commit. You're usually stuck manually copying and pasting, or trying to parse the messy JSON of the .ipynb file yourself.

You can find the full, ready-to-use code for this project on my GitHub.

In this guide, we'll solve this by building a robust MCP (Model Context Protocol) Server. This is a server that speaks a standard "language" (defined by an OpenAPI schema) that AIs and other tools can use. And we'll make one key design choice: we'll run it locally.

The "Why": A Local MCP Server

An MCP server is just a standard way for a model (like Gemini) to talk to a tool (like our server). My first idea was to deploy this as a public server on a platform like Render. But I hit a major security wall: a public web server cannot access your local files (like C:\Users\YourName\Documents). And for good reason!

The crucial moment was realizing the architecture is the key. We will build a true MCP server, but we will run it locally.

A local server (at 127.0.0.1) does have permission to access your local files. This makes it the perfect, secure architecture for a developer tool. As we'll see, you can still connect a cloud-based AI to it using a secure "tunnel" (like ngrok), which is a very impressive system to build.

The Step-by-Step Guide

We'll build this server from the ground up. Our API will have endpoints to create, edit, delete, move, and clear cells.

Step 1: The "Smart" Helper Functions

All the MCP server code will be written in the server.py file.

Before we build the API, we need two powerful helper functions.

First, a function to safely write our notebook. We'll use an "atomic write" (writing to a temporary file, then renaming) to make sure our notebook never gets corrupted, even if the script fails mid-save.

from flask import Flask, jsonify, request
import nbformat
import os
import tempfile

app = Flask(__name__)

def safe_write_notebook(nb, notebook_name):
    """Atomically writes a notebook to the specified file."""
    temp_path = ""
    try:
        with tempfile.NamedTemporaryFile(mode='w', delete=False, dir=os.path.dirname(notebook_name) or '.') as f:
            nbformat.write(nb, f)
            temp_path = f.name
       # This rename is "atomic" - it happens instantly
        os.rename(temp_path, notebook_name)
    except Exception as e:
        # If any error occurs, clean up the temp file
        if temp_path and os.path.exists(temp_path):
            os.remove(temp_path)
        raise e

Second, a smart function to load our notebook. What if the file doesn't exist? What if it's empty or corrupted? This function handles all of that.

def get_or_create_notebook(notebook_name):
    """Reads a notebook file. If it doesn't exist, creates a valid, empty one."""
    if not os.path.exists(notebook_name):
        print(f"Notebook '{notebook_name}' not found. Creating a new one.")
        # Create a new, empty notebook in memory
        nb = nbformat.v4.new_notebook()
        with open(notebook_name, 'w') as f:
            nbformat.write(nb, f)

    with open(notebook_name, 'r') as f:
        try:
            return nbformat.read(f, as_version=4)
        except nbformat.reader.NotJSONError:
        # If the file is empty or corrupt, return a new in-memory notebook
            print(f"Warning: '{notebook_name}' is empty or corrupted. Initializing a new notebook.")
            nb = nbformat.v4.new_notebook()
            return nb

Step 2: Building the Flask Server Endpoints

Now that we have our helpers, building the API is clean and simple. We just need to import Flask and set up our routes.

from flask import Flask, jsonify, request
from nbformat.v4 import new_code_cell, new_markdown_cell

Let's build the /create_cell endpoint. It will:

1. Get the notebook_name, content, and cell_type from the JSON request.

2. Call our get_or_create_notebook helper.

3. Create and append the new cell.

4. Call our safe_write_notebook helper to save.

@app.route('/create_cell', methods=['POST'])
def create_cell():
    try:
        data = request.get_json()
        if not data or 'notebook_name' not in data or 'cell_type' not in data or 'content' not in data:
            return jsonify({'error': 'Missing notebook_name, cell_type, or content'}), 400

        notebook_name = data['notebook_name']
        cell_type = data['cell_type']
        content = data['content']

       # Load the notebook, or create it if it doesn't exist
        nb = get_or_create_notebook(notebook_name)

        # Create the new cell object based on type
        if cell_type == 'code':
            new_cell = nbformat.v4.new_code_cell(content)
        elif cell_type == 'markdown':
            new_cell = nbformat.v4.new_markdown_cell(content)
        else:
            return jsonify({'error': 'Invalid cell_type. Must be "code" or "markdown"'}), 400

       # Add the new cell to the notebook
        nb.cells.append(new_cell)

        # Save the changes back to the file
        safe_write_notebook(nb, notebook_name)
        return jsonify({'message': f'Cell created successfully in {notebook_name}', 'total_cells': len(nb.cells)}), 200

    except Exception as e:
        return jsonify({'error': str(e)}), 500

The /edit_cell endpoint follows the same pattern. The only difference is the "modify" step, where we add validation. This code checks if the cell_number is within the valid range of the notebook. If it's out of range, it returns an error; otherwise, it edits the cell and saves.

@app.route('/edit_cell', methods=['POST'])
def edit_cell():
    try:
        data = request.get_json()
        if not data or 'notebook_name' not in data or 'cell_number' not in data or 'content' not in data:
            return jsonify({'error': 'Missing notebook_name, cell_number, or content'}), 400

        notebook_name = data['notebook_name']
        cell_number = data['cell_number']
        content = data['content']

        # Load the notebook
        nb = get_or_create_notebook(notebook_name)

        # --- Cell Index Validation ---
        if not isinstance(cell_number, int) or not (0 <= cell_number < len(nb.cells)):
            return jsonify({'error': f'Cell number {cell_number} is out of range for {notebook_name}'}), 400

        # Update the cell's source content
        nb.cells[cell_number]['source'] = content

        # Save the modified notebook
        safe_write_notebook(nb, notebook_name)
        return jsonify({'message': f'Cell {cell_number} in {notebook_name} edited successfully'}), 200

    except Exception as e:
        return jsonify({'error': str(e)}), 500

(You can add the delete_cell, move_cell, and clear_notebook functions here following the same pattern.)

Step 3: Creating the "Menu" (The openapi.yaml File)

We've built the "engine" (server.py), but now we need the "user manual." In the world of MCP, this is an OpenAPI (formerly Swagger) file.

This simple text file, openapi.yaml, describes our API in a standard format that any AI or tool can understand. It tells the AI: "Here are my functions, like /create_cell, and here are the 'ingredients' they need, like notebook_name and content."

Create a new file named openapi.yaml in the same project folder and add this code:

openapi: 3.0.0
info:
  title: Local Jupyter Notebook MCP Server
  version: 2.0.0
  description: An API to programmatically control local Jupyter Notebook files.
paths:
  /create_cell:
    post:
      summary: Creates a new cell in a specified notebook.
      description: If the notebook does not exist, it will be created.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                notebook_name:
                  type: string
                  description: "The path to the notebook file (e.g., 'my_notebook.ipynb')."
                content:
                  type: string
                  description: "The content for the new cell."
                cell_type:
                  type: string
                  description: "Type of cell to create ('code' or 'markdown')."
                  default: 'code'
              required:
                - notebook_name
      responses:
        '200':
          description: Cell created successfully

This small snippet clearly defines the function, its inputs (like notebook_name and content), and what to expect as a response. We would create similar definitions for /edit_cell, /delete_cell, and all our other functions.

You can see the complete, final openapi.yaml file in the project's GitHub repository.

Step 4: Running and Testing Your Server

Finally, we just need to run our server. Add this to the bottom of your server.py file:

if __name__ == '__main__':
    # This is the corrected line:
    print("Starting local notebook server on http://127.0.0.1:5001")
    app.run(debug=True, port=5001)

Now, run your server from your terminal:

python server.py

Open a second terminal and send a curl request. This command will create a brand new notebook my_test.ipynb and add a markdown cell to it.

# This is the corrected command:
curl -X POST -H "Content-Type: application/json" -d "{\"notebook_name\": \"my_test.ipynb\", \"content\": \"# Hello Server!\", \"cell_type\": \"markdown\"}" http://127.0.0.1:5001/create_cell

Check your folder. You'll see my_test.ipynb has been created!

Step 5: Connecting Your Local Server to a Cloud AI This is the final, most powerful step. How do we let a cloud-based AI (like Gemini) talk to our private local server?

We use a free tool called ngrok to create a secure "tunnel."

Leave your server running in Terminal 1.

Install ngrok[https://ngrok.com/] (it's a single file download) and sign up for a free account. Follow the insturtcions as per given on the website.

Open a second terminal and run this command:

ngrok http 5001

ngrok will give you a public URL, like this:

Forwarding https://<some-random-name>.ngrok.io -> http://localhost:5001

This https... URL is now the public address for your local server.

Now, you can go to an AI platform like Google AI Studio or the Anthropic Console:

Find the section for "Tools" or "Tool Use."

Give it your openapi.yaml file (the "menu" for your API).

When it asks for the Server URL or "Base URL," paste in your new ngrok URL.

Now, when you ask the AI, "Hey, use my notebook tool to create a new cell in my_test.ipynb," the AI will send its request to the public ngrok URL, which will forward it to your local server.py, which will then edit your local file.

Conclusion

We just built a complete, robust local MCP server from scratch. This is more than just a script; it's a real piece of software architecture.

But a server is only as good as the tools that use it.

This project opens up many exciting possibilities. The next logical step would be to build a custom AI agent that uses this exact server to intelligently manage, refactor, and create new notebooks. If you enjoyed this project and want to see more content on building developer tools and AI agents, be sure to follow me here on Hashnode!

What's the first automation script you'll build with this? Let me know in the comments below!