ipynb-mcp

Go-based MCP server for safe .ipynb notebook editing through explicit tools.

The server exposes notebook operations without returning raw notebook JSON to the assistant. Notebook JSON parsing, validation, and writes are handled internally.

Features

• Read notebook as human-readable preview (read_notebook)
• Token-efficient output previews with truncation controls
• Chunked output retrieval for large code outputs (read_cell_output)
• Create notebook with nbformat 4.5 and caller-provided initial cells (create_notebook)
• Insert/update markdown and code cells with explicit tools (single or batch mode)
• Delete cells by index (single or batch mode)
• Index and extension validation with clear errors
• Safe file writes (temp file + replace)
• Preserves notebook-level metadata and unrelated cell fields where possible

Tools

1. read_notebook
2. create_notebook
3. insert_markdown_cell
4. insert_code_cell
5. update_markdown_cell
6. update_code_cell
7. delete_cell
8. read_cell_output

Tool Input Notes

• create_notebook: accepts path and optional cells.
• insert_markdown_cell / insert_code_cell: single mode (index, source) or batch mode (indices, sources).
• update_markdown_cell / update_code_cell: single mode (index, source) or batch mode (indices, sources).
• delete_cell: single mode (index) or batch mode (indices).

Run

go run .

Install

Build a local binary:

go build -o ipynb-mcp .

Then configure your AI client to run the binary as an MCP stdio server.

Prebuilt binaries are also published in GitHub Releases for:

• Windows (amd64, arm64)
• Linux (amd64, arm64)
• macOS / Darwin (amd64, arm64)

See full per-client setup in DOCS.

Example MCP Config (Local)

{
  "mcpServers": {
    "ipynb": {
      "command": "go",
      "args": ["run", "."],
      "cwd": "/path/to/ipynb-mcp"
    }
  }
}

You can also use a built binary:

{
  "mcpServers": {
    "ipynb": {
      "command": "/path/to/ipynb-mcp/ipynb-mcp"
    }
  }
}

Tests

go test ./...

License

MIT