DEV Community

cshara
cshara

Posted on

I created small mcp server for Jupyter Notebook.

#agents #mcp #python #showdev

Introduction

When working with AI agents like Claude or Antigravity, one common hurdle is dealing with Jupyter Notebook (.ipynb) files.

While agents are great at writing code, directly editing the complex JSON structure of a notebook can lead to corruption. Furthermore, security restrictions often prevent agents from executing code directly in a notebook environment.

To solve this, I developed Easy Jupyter Editor MCP — a lightweight Model Context Protocol (MCP) server that allows AI agents to structurally and safely edit notebook files.

What is it?

easy-jupyter-editor-mcp is a tool that exposes standard notebook manipulation functions to any MCP-compliant client. It uses the nbformat library to ensure that any changes made to the .ipynb file are valid and won't break the JSON structure.

Why structural editing?

  1. Safety: No more broken JSON syntax errors when an AI tries to append a cell.
  2. Execution Bypassing: Sometimes you just want the agent to write the code so you can review and run it yourself.
  3. Simplicity: It doesn't require a running Jupyter kernel, making it extremely fast and lightweight.

Key Features

The server provides several tools that agents can use:

  • read_notebook: Get a summary of all cells.
  • get_cell: Retrieve the exact code of a cell.
  • add_cell / delete_cell: Manage the notebook structure.
  • edit_cell: Update existing code or markdown.
  • create_notebook: Bootstrap a new notebook from scratch.

How to use it

Prerequisites

This MCP server is designed to work seamlessly with uv. If you haven't installed it yet, you can do so with a single command:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

For other platforms, please refer to the official uv documentation.

Configuration for Claude Desktop

To use this MCP server with Claude Desktop, edit your claude_desktop_config.json file:

  • Path: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
  • Content: 
{
  "mcpServers": {
    "easy-jupyter-editor": {
      "command": "uvx",
      "args": ["easy-jupyter-editor-mcp"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Configuration for Antigravity

To use this with Antigravity, you need to add the same configuration to the Antigravity config file.
(Note: The path varies by installation, please check your Antigravity documentation, typically found in ~/Library/Application Support/Antigravity/config.json).

Configuration for Antigravity Extension in VS Code

VS Code itself does not support MCP natively; you need an extension (like Antigravity) to act as the MCP client.

If you are using the Antigravity extension in VS Code, you can configure the MCP server directly through the editor's UI:

  1. Open Settings (Cmd + ,).
  2. Search for Antigravity.
  3. Locate the MCP Servers (or similar) section in the Antigravity extension settings.
  4. Add the server configuration JSON.

Setting it up in VS Code allows the agent to visually interact with your notebooks in real-time.

Workflow

Once configured, the workflow is simple:

  1. Request: Ask the agent to modify a notebook.
  2. Action: The agent uses easy-jupyter-editor-mcp tools to safely update the .ipynb file.
  3. Review: You see the updates instantly in VS Code and can run the cells yourself.

Behind the Scenes

This project was born out of a specific need: giving the Antigravity AI agent the ability to assist in notebook development without granting it full execution permissions or risking file corruption.

The project is open source and available on PyPI. Check it out if you're building AI-assisted data science workflows!

Happy coding with AI!

Top comments (0)