SpiceBook Integration

These tools bridge mcltspice with SpiceBook, a web notebook service for SPICE circuits. You can publish LTspice designs as interactive, runnable notebooks --- shareable via URL --- and test ngspice compatibility without leaving your MCP session.

spicebook_publish

Publish an LTspice netlist as an interactive SpiceBook notebook. Reads the netlist from a string or file, converts it from LTspice dialect to ngspice (stripping .backanno, Rser=, Windows paths), builds notebook cells with an intro and the netlist, and creates the notebook via SpiceBook’s compose endpoint.

Parameter	Type	Default	Description
netlist_text	`str \| None`	`None`	Netlist as a string. Mutually exclusive with `netlist_path`.
netlist_path	`str \| None`	`None`	Path to a `.cir`, `.net`, `.sp`, `.spice`, or `.asc` file on disk.
title	`str`	`"Untitled Circuit"`	Notebook title, shown in the listing and intro cell.
description	`str \| None`	`None`	Circuit description, rendered in the intro markdown cell.
tags	`list[str] \| None`	`None`	Tags for categorization and search (e.g. `["filter", "audio"]`).
run	`bool`	`False`	If `True`, SpiceBook runs the simulation immediately on publish.

Returns: A dict with notebook_id, url (direct link to the notebook), cell_count, and conversion_warnings (list of strings describing any LTspice-to-ngspice changes).

Example

{
  "notebook_id": "rc-lowpass-filter-a3b2c1d4",
  "url": "https://spicebook.warehack.ing/notebooks/rc-lowpass-filter-a3b2c1d4",
  "cell_count": 2,
  "conversion_warnings": [
    "Stripped Rser= from: C1 out 0 100n Rser=0.1"
  ]
}

spicebook_simulate

Run a netlist via SpiceBook’s ngspice engine without creating a notebook. Useful for testing whether a netlist is ngspice-compatible before publishing. The netlist is converted from LTspice dialect first.

Parameter	Type	Default	Description
netlist_text	`str \| None`	`None`	Netlist as a string. Mutually exclusive with `netlist_path`.
netlist_path	`str \| None`	`None`	Path to a netlist file on disk.

Returns: The simulation result from SpiceBook’s ngspice engine, plus conversion_warnings if any LTspice constructs were modified.

Example

{
  "stdout": "...",
  "stderr": "",
  "returncode": 0,
  "conversion_warnings": []
}

spicebook_list

List all notebooks on SpiceBook. No parameters.

Returns: A dict with notebooks (array of notebook summaries) and count.

Example

{
  "notebooks": [
    {
      "id": "rc-lowpass-filter-a3b2c1d4",
      "metadata": {
        "title": "RC Lowpass Filter",
        "tags": ["filter", "analog"],
        "modified": "2026-02-15T21:45:24Z"
      }
    }
  ],
  "count": 1
}

spicebook_get

Retrieve a full SpiceBook notebook with all cells and outputs.

Parameter	Type	Default	Description
notebook_id	`str`	---	The notebook ID to retrieve.

Returns: The complete notebook object including metadata (title, tags, engine, timestamps), cells (array of cell objects with type, source, and outputs), and spicebook_version.

Example

{
  "spicebook_version": "2026-02-13",
  "metadata": {
    "title": "RC Lowpass Filter",
    "engine": "ngspice",
    "tags": ["filter"],
    "created": "2026-02-15T21:45:24Z",
    "modified": "2026-02-15T21:45:24Z"
  },
  "cells": [
    {
      "id": "cell-abc123",
      "type": "markdown",
      "source": "# RC Lowpass Filter\n\nFirst-order filter with fc = 1.59 kHz",
      "outputs": []
    },
    {
      "id": "cell-def456",
      "type": "spice",
      "source": "V1 in 0 AC 1\nR1 in out 1k\nC1 out 0 100n\n.ac dec 100 1 1meg\n.end",
      "outputs": []
    }
  ]
}

spicebook_delete

Delete a SpiceBook notebook.

Parameter	Type	Default	Description
notebook_id	`str`	---	The notebook ID to delete.

Returns: {"deleted": true, "notebook_id": "..."} on success.

Configuration

SpiceBook tools read two environment variables:

Variable	Default	Description
`SPICEBOOK_URL`	`https://spicebook.warehack.ing`	Base URL of the SpiceBook instance.
`SPICEBOOK_TIMEOUT`	`30`	HTTP request timeout in seconds.

No authentication is required.

Error handling

All SpiceBook tools return structured error dicts on failure:

Unreachable: {"error": "SpiceBook not reachable at <url>", "hint": "Check connectivity or set SPICEBOOK_URL env var"}
Timeout: {"error": "SpiceBook request timed out"}
HTTP error: {"error": "HTTP <status>", "detail": "<response body>"}