copperflow

Connect your agent

An agent needs two things to design with copperflow: the tools, which come from copperflow's MCP server, and the way of working, which comes from the copperflow skill. Both are in the package you installed.

Before you start

Install copperflow (it needs Node.js 22 or newer) and make a folder for your board.

npm install -g copperflow
mkdir my-board
cd my-board

The MCP server is the command copperflow mcp. Your agent starts it and talks to it; you never run it yourself. It works on one project folder: the folder it is started in, or the one you name with --root.

To try copperflow without installing it, use the command npx with the arguments -y copperflow mcp wherever these steps say copperflow mcp. The first start takes about a quarter of a minute while npm fetches the package.

We have tested these steps with Claude Code. The entries for the other agents follow each program's own documentation for local MCP servers; if one does not work for you, please open an issue.

Claude Code

In the board's folder, add the server and install the skill:

claude mcp add copperflow -- copperflow mcp
copperflow skill

Then check the connection:

claude mcp list

The line for copperflow ends with Connected. Start a new session in the folder so Claude Code picks up the server and the skill.

Claude Desktop

Open Settings, then Developer, then Edit Config. Add copperflow to the file it opens, with the full path of your board's folder, and restart the app.

{
  "mcpServers": {
    "copperflow": {
      "command": "copperflow",
      "args": ["mcp", "--root", "/full/path/to/my-board"]
    }
  }
}

Cursor

Create .cursor/mcp.json in the board's folder and open that folder in Cursor.

{
  "mcpServers": {
    "copperflow": {
      "command": "copperflow",
      "args": ["mcp", "--root", "/full/path/to/my-board"]
    }
  }
}

VS Code

Create .vscode/mcp.json in the board's folder, open the folder, and use Copilot Chat in agent mode.

{
  "servers": {
    "copperflow": {
      "type": "stdio",
      "command": "copperflow",
      "args": ["mcp", "--root", "${workspaceFolder}"]
    }
  }
}

Codex

Add copperflow to ~/.codex/config.toml:

[mcp_servers.copperflow]
command = "copperflow"
args = ["mcp", "--root", "/full/path/to/my-board"]

Gemini CLI

Create .gemini/settings.json in the board's folder and start Gemini CLI there.

{
  "mcpServers": {
    "copperflow": {
      "command": "copperflow",
      "args": ["mcp", "--root", "/full/path/to/my-board"]
    }
  }
}

Any other agent

Any program that can start a local MCP server over standard input and output can use copperflow. Give it this command, with your board's folder:

copperflow mcp --root /full/path/to/my-board

Agents that run only in a web browser cannot start a program on your computer, so they cannot connect. Use a desktop or terminal agent.

Let the agent set itself up

An agent that can run commands can do the steps above for you. In the board's folder, say:

Set up copperflow for yourself here: follow https://copperflow.kurpeeren.com/llms.txt

That page holds the same steps as plain text, written for an agent to read. Most programs load their MCP servers when a session starts, so the tools appear in the next session, not in the one that added them: the agent will ask you to start a new one.

The skill

The skill is a short guide written for agents: which tool to call at each step of a design, what its answer looks like, how to respect your locks and notes, and reference pages on parts, copper and design rules.

A second skill, copperflow-plan, makes the agent plan before it draws. It asks you every question the design needs in one message (what the board does, how many inputs and outputs, the supply, the connectors), splits the board into blocks with named inputs and outputs, and designs a block that repeats only once: eight inputs are one block used eight times.

Agents with skills
Run copperflow skill in the board's folder. It copies both skills to .claude/skills, where Claude Code finds them. Add --global to install them once for every project instead.
Agents without skills
Nothing to install. The server tells the agent to call its guide tool, which answers with the same texts, the planning one included. The agent reads each once in a session.

Check that it works

In a new session, ask your agent:

Call copperflow's project_status and tell me what it says.

In an empty folder the answer is:

No PROJECT.md yet: write the Intent and Blocks with set_project.
Circuits: none yet (new_circuit starts one)

Now ask it to open the editor:

Open copperflow.

The agent starts the editor for this folder and opens it in your browser. An editor it started stops by itself an hour after you close the last tab. You can also start it yourself in a second terminal, in the same folder:

copperflow studio

Then ask for a board:

Design a CAN bus node: an MCP2515 controller, a TJA1051 transceiver, an 8 MHz crystal, one header for SPI and one for the bus. Two layers, as small as it routes.

For a chip that is not in the parts library, the agent finds and reads the datasheet with its own web access and writes the part from it. copperflow records the link and the page, and marks the part as unverified until you have checked it yourself.

Modules and libraries

A module is a block that has already been drawn: a sheet with named ports and the parts it uses. copperflow comes with a small library of them, and the agent places one instead of drawing it again:

Use copperflow/RelayDriver for the output, switched from the controller's pin.
copperflow/RelayDriver
A 12 V relay switched by a 3.3 V or 5 V logic pin, with its flyback diode and an LED.
copperflow/DigitalInput24V
One 24 V input brought down to a logic pin: a divider, a zener clamp and a filter.
copperflow/CanNode
An MCP2515 controller, a TJA1051 transceiver, an 8 MHz crystal and a termination resistor.

Three example boards built from them are in the examples folder. A block of your own goes on your shelf when you ask the agent to save it as a module.

Your own library is a git repository, or a folder, with one folder for each module, at the top or under modules/. Add it by a name of your choice:

copperflow library add mine https://github.com/you/your-modules

copperflow library lists your libraries, copperflow library update fetches the newest commit and copperflow library remove mine forgets one. The agent then sees mine/<Name> beside the built-in modules.

A circuit file is code, so copperflow takes a sheet from a library only when it holds nothing but parts and connections, and it takes the parts as data. Every module reads as not verified, the built-in ones too, until you have checked it and run copperflow modules verify mine/<Name> --by <your name>. No agent can do that for you.

More to ask for

The agent has a tool for each of these, and the same thing is a command in your terminal.

"Show me what you changed"
The agent says what a change did and draws it on the board: what was added, removed and moved. In the editor, each row of the Log has Show. In a terminal: copperflow history <id>.
"Does this block do what it says?"
simulate finds the DC operating point of a circuit or one block from ideal sources and simple part models. It knows no time, frequency, temperature or tolerance, and chips are not modelled. A module carries its own cases, such as the output voltage at 24 V in.
"Show me the board as it will be made"
copperflow render <file> --view board draws the bare board from its fabrication layers: mask, finish, print and holes. --view 3d and the editor's 3D tab stand the parts on it as simple shapes, not their real models. copperflow glb <file> writes the same as a 3D model file to turn in a viewer, and copperflow step <file> one for mechanical CAD.
"Is it ready to order?"
The bill of materials ends with whether the board is ready to order bare and for assembly, and names the lines with no supplier part number. copperflow export <file> writes the Gerbers, drills, pick-and-place file, a STEP model and a picture of each side.
"Which pin is which, for the firmware?"
copperflow pins <file> lists the net on each pin of the chips and connectors, as a table, CSV or a C header.
"This pair is USB, keep it at 90 ohms"
Net classes take an impedance, a differential pair, a longest length and matched groups, and the checks report what breaks them. The figures are estimates, and the router does not yet route a pair together or tune lengths.
"Start from my KiCad board"
copperflow import kicad board.kicad_pcb makes a new circuit from a KiCad 6 or newer board: outline, parts, nets, tracks, vias and pours. The parts arrive not verified.

Checking a library part against its datasheet stays yours. Verify in the editor opens the footprint with its dimensions, each pin as a row to tick and the datasheet beside them, and marks the part verified only when every row is ticked.

If it does not connect

The agent cannot start copperflow
Run copperflow --help in a terminal. If the command is not found, install it again with npm install -g copperflow and open a new terminal.
It starts in a terminal but not from the agent, on Windows
Some programs cannot start a command installed by npm directly. Use cmd as the command and "/c", "copperflow", "mcp", "--root", "C:\\path\\to\\my-board" as the arguments.
It reports an old Node.js
node --version must print 22 or newer.
The agent sees no circuits, or the wrong ones
The server is working on another folder. Name the board's folder with --root, as in the examples above.