circuitjs-mcp

这是一个 MCP 服务器，让 AI 代理能够操作 Falstad CircuitJS1 电路仿真器。由于它是标准的 stdio MCP 服务器，因此任何支持 MCP 的客户端（Claude Code、Codex CLI、Claude Desktop、Cursor 等）都可以使用。

CircuitJS1 是 Paul Falstad 的电路仿真器——早期以 Java Applet 版 “Circuit Simulator Applet” 广为人知，如今在 falstad.com/circuit 上以浏览器形式运行——的 HTML5/JavaScript 版名称。随着浏览器停止支持 Java Applet，Iain Sharp 使用 GWT 将其移植到 JavaScript，仿真引擎和电路文本格式都与 Applet 版相同（Applet 时代的电路文件可以直接读取）。本服务器使用的 JavaScript 接口是 CircuitJS1 中新增的功能，Applet 版没有。

在无头 Chromium (Playwright) 中启动编译好的 CircuitJS1 Web 应用（随附在 webapp/ 中，可离线运行），并将其 JavaScript 接口 公开为 MCP 工具。仿真器的状态会跨工具调用保留（可以交互式地完成：加载电路 → 运行 → 测量 → 改写电路）。

设置

前提条件：Node.js 18 或更高版本。

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

如果因环境原因难以执行 playwright install chromium，可以使用现有的 Chrome/Chromium：

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

Related MCP server: circuit-sim-mcp

注册到 MCP 客户端

启动命令在所有客户端中都相同：node /絶対パス/circuitjs-mcp/server.mjs

设置环境变量 CIRCUITJS_HEADFUL=1 后，会显示浏览器窗口，人类也可以像代理一样直接操作同一个仿真器（协作模式）。下面所有示例都带这个变量。不需要时请去掉。

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

配置文件方式的客户端（Claude Desktop 的 claude_desktop_config.json、Cursor 的 mcp.json 等）：

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

screenshot 工具会将 PNG 作为 MCP 图像内容返回。在不支持图像显示的客户端中，请使用 save_path 参数将其保存为文件。

工具列表

使用示例（给代理的指令示例）

• “搭一个 1kΩ 和 1µF 的 RC 低通滤波器，输入 1kHz 方波，获取 5ms 的输出波形”

• “读取这个电路（粘贴文本），列出每个电阻的功耗”

• “给我看电路的截图”

在想要测量的位置放置 带标签的节点（元件类型 207，例：207 336 128 400 128 4 out），就可以通过 {"node":"out"} 探针或 circuit_state 的 nodes 读取电压。元件级别的电流和电压用 circuit_load / circuit_state 返回的 index 指定。

从脚本直接操作

如果想不经由 MCP 客户端而直接从脚本调用工具，可以使用 drive.mjs。它以子进程方式启动服务器，按顺序执行放在命令目录中的 JSON 文件（cmd-1.json、cmd-2.json、...），并将结果写入 res-N.json：

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

文件请先以临时名称写入，再通过 rename 放置（避免读取到写入中的文件）。

环境变量

限制

• run_transient 的仿真速度取决于电路的 $ 行中的仿真速度设置和 CPU。如果实际时间过长，会因 wallTimeoutMs 超时而中断，并返回部分数据（可通过 reason 字段判断）。

• 电路的“编辑”基本方法是改写 Falstad 文本后重新执行 circuit_load（导入会重置时间）。

• 仅支持瞬态分析（因为 CircuitJS1 本身没有 AC 小信号分析等功能）。频率特性可以通过扫频并重复执行 run_transient 来获得。

许可证

本仓库整体以 GPL-2.0-or-later 协议提供（COPYING.txt）。

• CircuitJS1 是 Paul Falstad / Iain Sharp 开发的 GPLv2+ 软件。webapp/ 是其编译后的构建（未修改），对应的源代码可在 pfalstad/circuitjs1（原作）和 code4fukui/circuitjs1 的 pages 分支（本构建的获取来源）中获取。

• 服务器代码（server.mjs、drive.mjs、test-client.mjs）© 2026 Suzu（涼鈴），GPL-2.0-or-later。