Skip to main content
Glama
Observable Notebook Kit Debug MCP Server

Observable Notebook Kit Debug MCP Server

by rreusser

mcp-observable-notebook-kit-debug

MCP server for debugging Observable Notebook Kit notebooks.

Enables AI assistants to inspect values, view errors, and capture canvas output from notebooks running in a web browser. For a fully working example, see ./example.

Why?

The Observable Desktop is really cool, but it had some limitations. For one, okay, so I paid Anthropic some money for Claude Code, but it's not the right Anthropic integration to be able to configure an API key in the app, so I'm out of luck. And I was trying to get some WebGPU experiments running, but the app didn't have access to a WebGPU context. So one thing led to another, and I wrote a quick MCP server to exfiltrate values from notebooks running in the browser.

Related MCP server: threejs-devtools-mcp

Setup

1. Install the package

npm install @rreusser/mcp-observable-notebook-kit-debug

2. Add the Vite plugin

In your vite.config.js:

import { defineConfig } from "vite";
import { observable, config } from "@observablehq/notebook-kit/vite";
import { debugNotebook } from "@rreusser/mcp-observable-notebook-kit-debug";

export default defineConfig({
  ...config(),
  plugins: [debugNotebook(), observable()],
});

3. Run the dev server

vite -c vite.config.js

4. Configure the MCP server

Add to your .mcp.json:

{
  "mcpServers": {
    "Notebook": {
      "command": "mcp-notebook-kit-debug",
      "args": []
    }
  }
}

Note that you might need an absolute path to the mcp-notebook-kit-debug bin, and you might be using opencode or some other tool, so this step could vary a bit.

5. Go!

You can now use an agent like Claude Code to poke and prod at notebooks running in a web browser, inspecting values and even capturing canvas output as images.

MCP Tools

Observable Runtime Tools

These tools interact directly with the Observable runtime's reactive graph.

Tool

Description

ListValues

List all named values in the Observable runtime's reactive graph

GetValue

Get a value from the runtime by name; returns images for Canvas/SVG elements

GetValues

Get multiple values at once (snapshot of runtime state)

GetValueMetadata

Get metadata: state, type, dependencies (inputs), and dependents (outputs)

GetDependencyGraph

Get the dependency graph showing how values depend on each other

SetInputValue

Set an input widget's .value property and trigger reactive updates

RuntimeEval

Evaluate an expression with access to all notebook variables

Browser Tools

These tools interact with the browser/DOM context, outside the Observable runtime.

Tool

Description

BrowserEval

Execute JavaScript in the browser (has DOM access but NOT Observable runtime)

GetElementContent

Get content from a DOM element by CSS selector; captures canvas/SVG as images

MouseClick

Simulate a mouse click at a position or on an element

MouseDrag

Simulate a mouse drag from start to end position

MouseHover

Simulate mouse hover at a position, triggering hover states and tooltips

MouseWheel

Simulate a mouse wheel scroll at a position

SendKeys

Simulate keyboard input to an element

Session Tools

These tools manage notebook connections and debug sessions.

Tool

Description

ListNotebooks

List all connected notebooks (use when multiple notebooks are open)

FocusNotebook

Set a default notebook for subsequent commands (when multiple are connected)

Refresh

Refresh the page and wait for notebook initialization

Navigate

Navigate a notebook to a different URL (e.g., switch from notebook-a to notebook-b)

GetConsoleMessages

View console logs from the current session

GetErrors

Get all errors (DOM-reported and values in rejected state)

Multi-Notebook Support

When multiple notebooks are open in different browser tabs, you can target a specific notebook using the notebook parameter on any tool:

# By path (without .html extension)
notebook: "index"
notebook: "second-notebook"

# By index
notebook: "0"
notebook: "1"

# By URL
notebook: "http://localhost:5173/"

If multiple notebooks are connected and you don't specify which one, the tool will return an error listing the available notebooks.

Use ListNotebooks to see all connected notebooks with their URLs and indices.

Navigating Between Notebooks

The Navigate tool allows you to navigate an open notebook to a different URL, or open a URL in your default browser if no notebooks are connected:

// If no notebooks are connected, opens URL in default browser
Navigate({ url: "http://localhost:5173/index.html" })

// Navigate to a different notebook (relative URL)
Navigate({ url: "/second-notebook.html" })

// Navigate using absolute URL
Navigate({ url: "http://localhost:5173/second-notebook.html" })

// Navigate a specific notebook (when multiple are open)
Navigate({ url: "/second-notebook.html", notebook: "index" })

// Skip waiting for page load (useful if target page doesn't have debug plugin)
Navigate({ url: "/some-page.html", wait_for_completion: false })

Behavior:

  • No notebooks connected: Opens the URL in your OS default browser

  • One notebook connected: Navigates that notebook's browser window to the new URL

  • Multiple notebooks connected:

    • Navigates the focused notebook (if you've used FocusNotebook)

    • Navigates the specified notebook (if notebook parameter provided)

    • Returns an error listing all notebooks (if no focus is set and no notebook specified)

The tool waits for the new page to load and initialize, similar to Refresh, and reports any errors that occur during initialization.

Value States

Values in an Observable notebook can be in one of three states:

  • fulfilled: The value has been computed successfully

  • pending: The value is still being computed (e.g., async/Promise)

  • rejected: The computation threw an error

The GetValue and GetValues tools return state information along with the value or error.

Image Support

GetValue automatically returns images inline for:

  • Canvas elements: Captured as PNG

  • SVG elements: Rendered to canvas and captured as PNG

No need to save to files - images are returned directly in the MCP response.

Runtime Evaluation

Use RuntimeEval to evaluate expressions in the Observable runtime context with access to all notebook variables. The body must use a return statement.

// Compute derived values from notebook variables
RuntimeEval({ body: "return number * 2 + rangeValue" })

// Filter or transform data
RuntimeEval({ body: "return data.filter(d => d.value > 0)" })

// Multi-statement expressions
RuntimeEval({
  body: `
    const doubled = number * 2;
    const added = doubled + rangeValue;
    return { doubled, added };
  `
})

// Persist the result as a named variable for later retrieval
RuntimeEval({
  name: "myResult",
  body: "return number * 2"
})

Dependencies are auto-detected from the expression. If name is provided, the result persists in the runtime and can be retrieved with GetValue. If name starts with _tmp_, it is automatically deleted after the value resolves.

Setting Input Values

Use SetInputValue to programmatically change the value of interactive input widgets created with Inputs.* (e.g., Inputs.range, Inputs.select, Inputs.text). This sets the widget's .value property and dispatches an input event, triggering reactive updates to dependent values.

// If the notebook has: slider = Inputs.range([0, 100])
SetInputValue({ name: "slider", value: 50 })

// If the notebook has: dropdown = Inputs.select(["A", "B", "C"])
SetInputValue({ name: "dropdown", value: "B" })

Mouse Interaction

Simulate mouse events for testing interactive visualizations:

  • MouseClick: Click at coordinates or on an element (supports left/middle/right buttons)

  • MouseDrag: Drag from start to end position with configurable duration

  • MouseHover: Hover at a position, dispatching mouseenter/mouseover/mousemove events

  • MouseWheel: Scroll at a position with deltaX/deltaY

All mouse tools accept an optional selector parameter to target a specific element, with coordinates relative to that element.

Keyboard Interaction

Use SendKeys to simulate keyboard input:

// Type plain text
SendKeys({ keys: "hello world" })

// Use special keys with braces
SendKeys({ keys: "{Enter}" })
SendKeys({ keys: "{Tab}" })
SendKeys({ keys: "{ArrowDown}" })

// Modifier combinations
SendKeys({ keys: "{Ctrl+a}" })  // Select all
SendKeys({ keys: "{Ctrl+c}" })  // Copy
SendKeys({ keys: "{Shift+Tab}" })  // Reverse tab

// Target a specific element
SendKeys({ selector: "#my-input", keys: "typed text{Enter}" })

// Hold modifiers for all keys
SendKeys({ keys: "abc", modifiers: { shiftKey: true } })  // Types "ABC"

Supported special keys: {Enter}, {Tab}, {Escape}, {Esc}, {Backspace}, {Delete}, {Insert}, {Space}, {ArrowUp}, {ArrowDown}, {ArrowLeft}, {ArrowRight}, {Home}, {End}, {PageUp}, {PageDown}, {F1}-{F12}.

License

© 2026 Ricky Reusser. MIT License.

Available Tools

20 tools
BrowserEvalA

Execute JavaScript in the browser context. Has access to the DOM but NOT the Observable runtime. Use RuntimeEval instead when you need access to notebook variables. Useful for DOM inspection, computed styles, or browser APIs.

Inputs: code (required), label, notebook, timeout_ms.

FocusNotebookA

Focus on a specific notebook. When multiple notebooks are connected, this sets which one receives commands by default. Use ListNotebooks to see available options.

Inputs: notebook (required).

GetConsoleMessagesA

Get console messages (log, info, warn, error) from the current or most recent session. Use this to debug console output without triggering a refresh.

Inputs: filter, channel, max_chars, session_id.

GetDependencyGraphA

Get the dependency graph from the Observable runtime showing how values depend on each other. Returns nodes (values) and edges (dependencies).

Inputs: name, depth, pattern, notebook, +3 more.

GetElementContentA

Get content from a DOM element by CSS selector. Auto-detects element type: returns text/HTML for regular elements, returns image content for canvas/SVG elements.

Inputs: selector (required), notebook, timeout_ms.

GetErrorsA

Get errors from the notebook. Returns both Vite build/parse errors (e.g. syntax errors that prevent the page from loading) and Observable runtime errors (values in a rejected state). If the page fails to load due to a syntax error, call this first — it will surface the Vite error even without a connected runtime. For console.error messages, use GetConsoleMessages with channel="error".

Inputs: verbose, notebook, timeout_ms.

GetValueB

Get a value from the Observable runtime by name. Returns the value along with its state (fulfilled, pending, or rejected). Automatically returns image content for Canvas and SVG elements.

Inputs: name (required), notebook, timeout_ms.

GetValueMetadataA

Get metadata about a value in the Observable runtime including its state, type, dependencies (inputs), and dependents (outputs) without fetching the full value.

Inputs: name (required), notebook, timeout_ms.

GetValuesA

Get multiple values from the Observable runtime at once. If no names provided, returns all values. Useful for getting a snapshot of the runtime state.

Inputs: names, notebook, timeout_ms.

ListNotebooksA

List all connected notebooks. Use this to see which notebooks are available before targeting a specific one.

Inputs: no named parameters.

ListValuesB

List all named values in the Observable runtime's reactive graph.

Inputs: notebook, timeout_ms.

MouseClickA

Simulate a mouse click at a position. Can target a specific element or coordinates.

Inputs: x, y, label, button, +3 more.

MouseDragA

Simulate a mouse drag from start to end position. Emits mousedown, mousemove events per animation frame, then mouseup.

Inputs: endX, endY, label, button, +6 more.

MouseHoverA

Simulate mouse hover at a position. Dispatches mouseenter, mouseover, and mousemove events to trigger hover states and tooltips.

Inputs: x, y, label, notebook, +2 more.

MouseWheelC

Simulate a mouse wheel scroll at a position.

Inputs: x, y, label, deltaX, +5 more.

RefreshA

Trigger notebook page refresh and wait for completion. Captures all logs and errors from the new session.

Inputs: notebook, timeout_ms, wait_for_completion.

RuntimeEvalA

Evaluate an expression in the Observable runtime context, with access to all notebook variables. Must use a return statement. Prefer this over Eval when computing derived values from runtime state. Examples: "return a + b" computes a sum; "return data.filter(d => d.value > 0)" filters a dataset.

Inputs: body (required), name, notebook, timeout_ms.

SendKeysA

Simulate keyboard input. Dispatches keydown, keypress (for printable characters), and keyup events to the target element.

Inputs: keys (required), notebook, selector, modifiers, +1 more.

SetInputValueA

Set the .value property of an input widget in the Observable runtime (e.g., Inputs.range, Inputs.select, Inputs.text) and dispatch an input event, triggering reactive updates to dependent values.

Inputs: name (required), value (required), notebook, timeout_ms.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 20 tools

    Disambiguation4/5

    Tools are largely purpose-specific: value retrieval is split into single/bulk/metadata/list, and evaluation is split into browser vs runtime contexts. A few boundaries require care—GetErrors vs GetConsoleMessages both surface errors, and GetValues with no names overlaps with ListValues—but descriptions clarify intended usage.

    Naming Consistency4/5

    Most tools follow a PascalCase VerbNoun pattern (ListNotebooks, GetValue, SetInputValue, SendKeys). Exceptions break the pattern: Refresh and Navigate are bare verbs, while BrowserEval/RuntimeEval and MouseClick/Drag/Wheel/Hover put the context or object before the action, making the convention less predictable.

    Tool Count3/5

    20 tools is at the high end for a debugger and feels slightly heavy, with multiple value-retrieval variants and five input-simulation tools. The breadth is defensible because the server covers runtime state, DOM inspection, and mouse/keyboard interaction, but it is borderline rather than clearly well-scoped.

    Completeness4/5

    The server covers the main notebook debugging loop: discover/connect notebooks, inspect runtime values and dependencies, read console/errors, manipulate inputs, and simulate interactions. Obvious gaps such as a dedicated screenshot or wait-for-condition tool are workaroundable via BrowserEval/RuntimeEval, but they are minor omissions.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Lets an AI assistant inspect a running Google Chrome or Microsoft Edge browser over the Chrome DevTools Protocol, reading console output, network traffic, DOM snapshots, errors, performance metrics, storage, and screenshots. It also supports live event subscriptions, screen-frame streaming, and one-shot export of everything into an offline-readable archive such as HAR, CSV, and a self-contained HTML report.
      36
      26 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to inspect a running Three.js or React Three Fiber scene in the browser, preview material, shader, light and camera edits live, and turn approved changes into ready-to-paste source code. Also supports website performance audits, video frame capture, and Playwright/Puppeteer test hooks.
      5,671 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to inspect and live-edit Three.js scenes in the browser — objects, materials, shaders, textures, lights, animation, performance and memory — then turn those previewed changes into ready-to-paste code. It also supports website audits, video frame capture, and Playwright/Puppeteer test workflows.
      5,671 npm
      MIT