circuitjs-mcp

Dies ist ein MCP-Server, der es KI-Agenten ermöglicht, den Falstad-CircuitJS1-Schaltungssimulator zu steuern. Da es sich um einen standardmäßigen stdio-MCP-Server handelt, funktioniert er mit jedem MCP-fähigen Client wie Claude Code, Codex CLI, Claude Desktop, Cursor usw.

CircuitJS1 ist die HTML5/JavaScript-Version des Schaltungssimulators von Paul Falstad – früher als Java-Applet-Version „Circuit Simulator Applet“ bekannt, der heute unter falstad.com/circuit im Browser läuft. Nachdem die Browser die Unterstützung für Java-Applets beendet hatten, portierte Iain Sharp sie mit GWT nach JavaScript. Sowohl die Simulationsengine als auch das Schaltungstextformat sind mit der Applet-Version identisch (Schaltungsdateien aus der Applet-Ära lassen sich direkt lesen). Die von diesem Server verwendete JavaScript-Schnittstelle wurde erst mit CircuitJS1 hinzugefügt und ist in der Applet-Version nicht vorhanden.

Er startet die kompilierte CircuitJS1-Webanwendung (webapp/ ist beigelegt, offline nutzbar) in einem Headless-Chromium (Playwright) und stellt deren JavaScript-Schnittstelle als MCP-Tools bereit. Der Zustand des Simulators bleibt über Tool-Aufrufe hinweg erhalten (Schaltung laden → laufen lassen → messen → Schaltung ändern ist interaktiv möglich).

Einrichtung

Voraussetzung: Node.js 18 oder höher.

cd circuitjs-mcp
npm install          # postinstall で Playwright の Chromium も入ります
npm test             # スモークテスト（RC回路の過渡応答が理論値と一致するか等を検証）

Falls playwright install chromium in Ihrer Umgebung schwierig ist, können Sie ein vorhandenes Chrome/Chromium verwenden:

export CIRCUITJS_CHROMIUM="/usr/bin/google-chrome"   # 例

Related MCP server: circuit-sim-mcp

Registrierung bei MCP-Clients

Der Startbefehl ist bei allen Clients gleich: node /絶対パス/circuitjs-mcp/server.mjs

Mit der Umgebungsvariable CIRCUITJS_HEADFUL=1 wird das Browserfenster angezeigt und ein Mensch kann den Simulator direkt genauso bedienen wie der Agent (Kollaborationsmodus). Alle folgenden Beispiele enthalten diese Variable. Wenn Sie sie nicht benötigen, lassen Sie sie weg.

Claude Code:

claude mcp add circuitjs -e CIRCUITJS_HEADFUL=1 -- node /絶対パス/circuitjs-mcp/server.mjs

Codex CLI:

codex mcp add circuitjs --env CIRCUITJS_HEADFUL=1 -- node /絶対パス/circuitjs-mcp/server.mjs

Clients mit Konfigurationsdatei (z. B. claude_desktop_config.json bei Claude Desktop, mcp.json bei Cursor):

{
  "mcpServers": {
    "circuitjs": {
      "command": "node",
      "args": ["/絶対パス/circuitjs-mcp/server.mjs"],
      "env": { "CIRCUITJS_HEADFUL": "1" }
    }
  }
}

Das screenshot-Tool gibt ein PNG als MCP-Bildinhalt zurück. Bei Clients ohne Bildunterstützung sollte es über das Argument save_path in eine Datei gespeichert werden.

Tool-Liste

Anwendungsbeispiele (Beispielanweisungen für den Agenten)

• „Baue einen RC-Tiefpass aus 1 kΩ und 1 µF und erfasse die Ausgangswellenform für 5 ms bei einem 1-kHz-Rechtecksignal.“

• „Lade diese Schaltung (eingefügter Text) und liste die Verlustleistung jedes Widerstands auf.“

• „Zeig mir einen Screenshot der Schaltung.“

Legen Sie an den zu messenden Stellen einen beschrifteten Knoten an (Elementtyp 207, z. B. 207 336 128 400 128 4 out). Dann lässt sich die Spannung über eine {"node":"out"}-Sonde oder über nodes in circuit_state auslesen. Ströme und Spannungen einzelner Elemente werden über den von circuit_load / circuit_state zurückgegebenen index angegeben.

Direkte Steuerung über Skripte

Wenn Sie die Tools ohne MCP-Client direkt aus einem Skript aufrufen möchten, können Sie drive.mjs verwenden. Es startet den Server als Unterprozess, führt die im Befehlsverzeichnis abgelegten JSON-Dateien (cmd-1.json, cmd-2.json, ...) der Reihe nach aus und schreibt die Ergebnisse nach res-N.json:

node drive.mjs /tmp/cjs-commands
# 別プロセスから: echo '{"tool":"circuit_state","args":{}}' > /tmp/cjs-commands/cmd-1.json

Dateien erst unter einem temporären Namen schreiben und dann per rename ablegen (um zu vermeiden, dass während des Schreibens gelesen wird).

Umgebungsvariablen

Einschränkungen

• Die Simulationsgeschwindigkeit von run_transient hängt von der Simulationsgeschwindigkeitseinstellung in der $-Zeile der Schaltung und der CPU ab. Dauert es in Echtzeit zu lange, wird die Ausführung durch wallTimeoutMs abgebrochen und es werden Teildaten zurückgegeben (erkennbar am Feld reason).

• Eine „Bearbeitung“ der Schaltung erfolgt im Wesentlichen durch Umschreiben des Falstad-Texts und erneutes Laden per circuit_load (beim Import wird die Zeit zurückgesetzt).

• Nur transiente Analyse (da CircuitJS1 selbst keine AC-Kleinsignalanalyse usw. besitzt). Der Frequenzgang lässt sich durch Variieren der Frequenz und wiederholtes run_transient ermitteln.

Lizenz

Das gesamte Repository wird unter GPL-2.0-or-later bereitgestellt (COPYING.txt).

• CircuitJS1 ist eine Software von Paul Falstad / Iain Sharp unter GPLv2+. webapp/ ist dessen kompilierter Build (unverändert); der zugehörige Quellcode ist in pfalstad/circuitjs1 (Original) und im pages-Zweig von code4fukui/circuitjs1 (Bezugsquelle dieses Builds) verfügbar.

• Servercode (server.mjs, drive.mjs, test-client.mjs) © 2026 Suzu (涼鈴), GPL-2.0-or-later.