circuitjs-mcp

An MCP server that lets AI agents operate the Falstad CircuitJS1 circuit simulator. Since it is a standard stdio MCP server, it works with any MCP-compatible client, including Claude Code, Codex CLI, Claude Desktop, and Cursor.

CircuitJS1 is the name of the HTML5/JavaScript version of Paul Falstad's circuit simulator—long familiar as the Java applet version, "Circuit Simulator Applet", and now running in the browser at falstad.com/circuit. When browsers discontinued Java applet support, Iain Sharp ported it to JavaScript with GWT; both the simulation engine and the circuit text format are shared with the applet version (circuit files from the applet era can be loaded as-is). The JavaScript interface this server uses is a feature added in CircuitJS1 and is not present in the applet version.

The server launches the compiled CircuitJS1 web app (bundled in webapp/, works offline) inside headless Chromium (Playwright) and exposes its JavaScript interface as MCP tools. Simulator state persists across tool calls, so you can interactively load a circuit → run it → take measurements → rewrite the circuit.

Setup

Prerequisites: Node.js 18 or later.

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

If playwright install chromium is difficult in your environment, you can use an existing Chrome/Chromium:

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

Related MCP server: circuit-sim-mcp

Registering with MCP cliients

The launch command is the same for every client: node /絶対パス/circuitjs-mcp/server.mjs

Adding the environment variable CIRCUITJS_HEADFUL=1 displays the browser window, allowing a human to operate the same simulator directly alongside the agent (collaboration mode). All examples below include this variable; remove it if not needed.

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 that use config files (Claude Desktop's claude_desktop_config.json, Cursor's mcp.json, etc.):

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

The screenshot tool returns a PNG as MCP image content. On clients that do not support image display, save it to a file with the save_path argument instead.

List of tools

Usage examples (sample instructions for an agent)

• "Build an RC low-pass filter with 1kΩ and 1µF, feed it a 1kHz square wave, and capture the output waveform for 5ms."

• "Load this circuit (paste the text) and list the power dissipation of each resistor."

• "Show me a screenshot of the circuit."

To measure a point of interest, place a labeled node (element type 207, e.g. 207 336 128 400 128 4 out); the voltage can then be read with a {"node":"out"} probe or via circuit_state's nodes. For per-element current and voltage, use the index returned by circuit_load / circuit_state.

Direct use from scripts

If you want to call the tools from a script without going through an MCP client, use drive.mjs. It starts the server as a child process, executes the JSON files placed in the command directory (cmd-1.json, cmd-2.json, ...) in order, and writes the results to res-N.json:

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

Write files under a temporary name and then rename them into place (to avoid reading them mid-write).

Environment variables

Limitations

• The simulation speed of run_transient depends on the simulation speed setting in the circuit's $ line and on the CPU. If it takes too long in wall-clock time, it is cut off by wallTimeoutMs and partial data is returned (distinguishable via the reason field).

• "Editing" a circuit basically means rewriting the Falstad text and calling circuit_load again (importing resets the time).

• Transient analysis only (CircuitJS1 itself does not have AC small-signal analysis, etc.). Frequency response can be obtained by sweeping the frequency and repeating run_transient.

License

This entire repository is provided under GPL-2.0-or-later (COPYING.txt).

• CircuitJS1 is GPLv2+ software by Paul Falstad / Iain Sharp. webapp/ is its compiled build (unmodified); the corresponding source code is available at pfalstad/circuitjs1 (the original) and the pages branch of code4fukui/circuitjs1 (where this build was obtained).

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