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 skillin the board's folder. It copies both skills to.claude/skills, where Claude Code finds them. Add--globalto install them once for every project instead. - Agents without skills
-
Nothing to install. The server tells the agent to call its
guidetool, 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?"
-
simulatefinds 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 boarddraws the bare board from its fabrication layers: mask, finish, print and holes.--view 3dand 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, andcopperflow 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_pcbmakes 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 --helpin a terminal. If the command is not found, install it again withnpm install -g copperflowand 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
cmdas the command and"/c", "copperflow", "mcp", "--root", "C:\\path\\to\\my-board"as the arguments. - It reports an old Node.js
node --versionmust 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.