@deepnote/mcp

MCP (Model Context Protocol) server for AI-assisted Deepnote notebook creation, editing, conversion, and execution.

This server follows MCP best practices:

• Server instructions: Usage guidance is injected into the AI system prompt
• MCP prompts: Reusable workflow templates for common notebook tasks
• Bounded toolsets: Focused tools with strict contracts
• Contracts first: Explicit schemas and side effects

Installation

# Install globally
npm install -g @deepnote/mcp

# Or run directly with npx
npx @deepnote/mcp

Usage with Cursor

Add to Cursor MCP settings:

{
  "mcpServers": {
    "deepnote": {
      "command": "npx",
      "args": ["@deepnote/mcp"]
    }
  }
}

Common settings locations:

• ~/.cursor/mcp.json
• ~/.cursor/config/mcp.json

MCP Prompts

The server exposes workflow templates through MCP prompts:

| Prompt | Description | | ----------------------- | ----------------------------------------------------------------- | | debug_execution | Debug notebook execution using snapshots and reruns | | create_notebook | Create a new Deepnote notebook with recommended structure | | convert_and_enhance | Convert from Jupyter/other formats and improve notebook structure | | fix_and_document | Fix issues and add documentation | | block_types_reference | Quick reference for block types and metadata | | best_practices | Best practices for well-structured interactive notebooks |

MCP Resources

The server exposes notebook resources for discovery:

| Resource URI | Description | | ---------------------- | ----------------------------------------------------- | | deepnote://examples | Example notebooks (if available in your installation) | | deepnote://workspace | All .deepnote files in the current workspace | | deepnote://file/... | Individual notebook summary by absolute file path |

Available Tools

Reading Tools

| Tool | Description | | ------------------- | ----------------------------------------------------------------------------------------------- | | deepnote_read | Read/analyze a notebook. Use include to request structure, stats, lint, dag, or all | | deepnote_cat | Show block contents with optional filters | | deepnote_validate | Validate YAML + schema structure | | deepnote_diff | Compare two .deepnote files structurally |

Writing Tools

| Tool | Description | | ------------------------- | -------------------------------------------------- | | deepnote_create | Create a new .deepnote file from a specification | | deepnote_add_block | Add a block to an existing notebook | | deepnote_edit_block | Edit a block's content and/or metadata | | deepnote_remove_block | Remove a block by ID | | deepnote_reorder_blocks | Reorder blocks in a notebook | | deepnote_add_notebook | Add a new notebook to an existing project |

Conversion Tools

| Tool | Description | | ----------------------- | ---------------------------------------------------- | | deepnote_convert_to | Convert Jupyter/Quarto/Percent/Marimo to .deepnote | | deepnote_convert_from | Convert .deepnote to Jupyter/Quarto/Percent/Marimo |

Execution Tools

Execution is handled by a single tool:

| Tool | Description | | -------------- | --------------------------------------------- | | deepnote_run | Run all notebooks, one notebook, or one block |

Scopes:

• Project level: deepnote_run with only path runs all notebooks
• Notebook level: pass notebook
• Block level: pass blockId (optionally also notebook)

deepnote_run supports .deepnote, .ipynb, .py, and .qmd inputs.

Snapshot Tools

Snapshots store outputs separately from source files.

| Tool | Description | | ------------------------- | ---------------------------------------------- | | deepnote_snapshot_list | List snapshots for a project | | deepnote_snapshot_load | Load latest or specific snapshot details | | deepnote_snapshot_split | Split source and outputs into separate files | | deepnote_snapshot_merge | Merge snapshot outputs back into a source file |

Examples

Create a notebook

Use deepnote_create with:
- outputPath: "analysis.deepnote"
- projectName: "Sales Analysis"
- notebooks:
  - name: "Notebook 1"
    blocks:
      - type: "text-cell-h1"
        content: "Sales Analysis"
      - type: "markdown"
        content: "Load data and explore trends"

Add a block and run only that block

1. Use deepnote_add_block with:
   - path: "analysis.deepnote"
   - block: { type: "code", content: "print('hello')" }
2. Use deepnote_run with:
   - path: "analysis.deepnote"
   - blockId: "<new block id>"

Lint and dependency analysis

Use deepnote_read with:
- path: "analysis.deepnote"
- include: ["lint", "dag"]

Convert from Jupyter and inspect

1. Use deepnote_convert_to with inputPath: "notebook.ipynb"
2. Use deepnote_read with:
   - path: "notebook.deepnote"
   - include: ["structure", "stats"]

Manage outputs with snapshots

# Split outputs for version control:
Use deepnote_snapshot_split with path: "analysis.deepnote"

# Inspect latest snapshot:
Use deepnote_snapshot_load with path: "analysis.deepnote"

# Restore outputs:
Use deepnote_snapshot_merge with sourcePath: "analysis.deepnote"

Development

Run from the monorepo root:

# Install dependencies
pnpm install

# Run in development mode
pnpm --filter @deepnote/mcp dev

# Build
pnpm --filter @deepnote/mcp build

# Test
pnpm --filter @deepnote/mcp test

License

Apache-2.0