# copperflow > A local PCB design program. A person edits in the Studio, a web editor that runs on their own computer; an agent > edits the same circuit files through an MCP server. There is no account and nothing is hosted: a project is a folder. ## If you are an agent asked to set copperflow up Do these in the folder that will hold the board. 1. Node.js: `node --version` must print 22 or newer. If it does not, stop and tell the person. 2. copperflow: `copperflow --help` prints the version on its first line. If the command is not found, run `npm install -g copperflow`. To use it without installing, give `npx -y copperflow mcp` as the server command instead of `copperflow mcp`; the first start takes about a quarter of a minute. 3. Add the MCP server to the program you run in: - Claude Code: `claude mcp add copperflow -- copperflow mcp`, then `copperflow skill` (copies the skills to `.claude/skills`), then `claude mcp list` (the line for copperflow ends with `Connected`). - Cursor: `.cursor/mcp.json` in the folder: `{ "mcpServers": { "copperflow": { "command": "copperflow", "args": ["mcp", "--root", ""] } } }` - VS Code: `.vscode/mcp.json` in the folder: `{ "servers": { "copperflow": { "type": "stdio", "command": "copperflow", "args": ["mcp", "--root", "${workspaceFolder}"] } } }` - Gemini CLI: `.gemini/settings.json` in the folder, the same shape as Cursor's. - Codex: in `~/.codex/config.toml`: `[mcp_servers.copperflow]`, `command = "copperflow"`, `args = ["mcp", "--root", ""]` - Claude Desktop: the person opens Settings, Developer, Edit Config and adds the same entry as Cursor's. - Any other program: start `copperflow mcp --root ` over standard input and output. On Windows, a program that cannot start a command installed by npm needs `cmd` as the command and `/c`, `copperflow`, `mcp`, `--root`, `` as the arguments. 4. Tell the person to start a new session in the folder. Most programs load their MCP servers when a session starts, so the tools do not appear in the session that added them. Until then, do not design the board by writing circuit files by hand: the tools keep the history and the person's locks. ## When the tools are connected - "Open copperflow", "show me the board": call `open_studio`. It starts the editor for the folder if none runs, opens it in the person's browser and answers with the address. The address holds a key for that session: give it to the person only. - First call in a session: `project_status`. - A new board starts with a plan, before any circuit file: `guide { topic: "planning" }`. Ask the person every question the design needs in one message. - Only the person unlocks a part, verifies a library part and verifies a module. There is no tool for these on purpose. - Before drawing a block, call `list_modules`: a module is a block already drawn, with named ports. copperflow ships `copperflow/RelayDriver`, `copperflow/DigitalInput24V` and `copperflow/CanNode`; `module_info` reads one and `use_module` brings it into the project. Every module reads NOT verified until the person has verified it: say so. - The person adds a library of their own with `copperflow library add `; its modules appear as `/`. No tool adds a library: ask the person to run the command. - A board drawn in a mechanical program comes in with `import_board`: the outline, the mounting holes and the keepouts from a DXF or SVG file (the file goes in the parameter named `dxf` either way). A `.kicad_pcb` file (KiCad 6 or newer) makes a new circuit from that board; its parts arrive not verified. - To show the person what you did: `recent_changes { id }` says what one change did and `render { change: id }` draws it; `since` covers everything after a change. - Before saying a block works, run `simulate`: the DC operating point from ideal sources and simple models (no time, no frequency, no tolerance; chips are not modelled). A module's card holds cases; `simulate` with `sheet` and no values runs them. - `render` with `view: "board"` is the bare board as made, drawn from the fabrication layers; `view: "3d"` adds the parts as simple shapes, not their real models. Look at one before asking the person to. - `export_model` writes the board and its parts as one 3D model file beside the circuit, for a board that is not finished too: `format: "step"` for mechanical CAD (parts as boxes), `format: "glb"` for a 3D viewer (the board as made, parts as simple shapes). - `guide { topic: "packages" }` lists the standard packages copperflow makes a footprint and a 3D shape for, each with the string to type as a part's `footprint`; `guide { topic: "packages sot" }` searches them, and a search that finds a few lists each one's pads and what each pad is. - `export_html` writes the whole design as one HTML file to hand to a person: every schematic page, the board, the 3D view and the BOM, with the fabrication files and the 3D models inside it as downloads. It opens offline. - `set_rules` changes `rules.yaml` (net classes, clearances, the 4-layer profile); `fit_board` also takes an exact width and height, an outline or the layer count; `render` takes `out` to write its picture to a file. - `add_text` with a `layer` puts words on the board's silkscreen; `import_graphic` places a drawing from an SVG or DXF file in the project on the silkscreen, as a solder-mask opening, or as copper. Copper with a `net` is that net's copper: it joins the net's pads and tracks and shorts against any other net. In an SVG the dark shapes are ink and light shapes over them are cut out. - Long tools (autoroute, autoplace, the exports, a 3D render) send MCP progress notifications when the client asks for them. When the person has the Studio open on the same project (in a browser or in the desktop app), every tool call also shows there as it runs, and `open_studio` brings the desktop app's window to the front instead of opening a browser. `copperflow connect claude-desktop` adds the server to Claude Desktop; the desktop app has the same button. - `bom` ends with whether the board is ready to order. `export_fabrication` writes the Gerbers, drills, pick-and-place file, a STEP model and a picture of each side; it refuses a circuit with errors. - Impedance, differential pairs and matched lengths are net classes in `rules.yaml` (`guide { topic: "design-rules" }`). The figures are estimates; the router does not route a pair together or tune lengths. ## Links - Steps for each program, for people: https://copperflow.kurpeeren.com/connect.html - Source: https://github.com/kurpeeren/copperflow - Package: https://www.npmjs.com/package/copperflow