fieldpuppet
Officialfieldpuppet
A Modbus TCP device simulator that an AI assistant can drive.
Start one small program and it can impersonate hundreds of Modbus devices at once, each on its own port. Through its built-in MCP server you tell an assistant such as Claude what you need in plain language — "set up three pumps and an energy meter, then make pump 2 stop answering for thirty seconds" — and the assistant creates the devices, plays the scenario and reports what your software asked them for.
It is meant for testing SCADA systems, gateways, historians, HMIs and any other software that talks Modbus, without real hardware on the desk.
Simulation only. This program never connects to real equipment. It only answers Modbus requests that are sent to it.
Developed and maintained by the team behind PLCGateway.
What it does
Many devices in one process. Each device gets its own TCP port automatically, or several devices share one port under different unit ids, like stations behind a serial gateway.
Ready-made templates. Energy meter, variable frequency drive, temperature controller, pump, tank — or define your own points one by one.
Values that move. Sine, ramp, random, random walk, counter and square-wave signals, in engineering units with scaling, for 16-bit, 32-bit and float registers.
Scenarios. A timeline of steps per device: change a value at 10 s, start a ramp at 30 s, break communication at 60 s.
Communication faults. Slow answers, no answer at all, Modbus exception replies, dropped connections — per device, with an optional time limit.
Traffic log. See exactly which registers your software polled and what it got back.
Live dashboard. A web page that shows every device, its points and current values, running scenarios and faults, and a plain-language feed of everything the assistant changed.
Works without AI too. Describe devices in a YAML file and run them from the command line.
Small and quick. One executable of about 2 MB with nothing to install. On a laptop-class machine, 1,000 devices with ten changing values each used about 11 MB of memory and under 1 % of one CPU core.
Related MCP server: kc_modbus_mcp
Install
Download the file for your system from the Releases page and unpack it. There is nothing else to install.
System | File |
Windows (64-bit) |
|
macOS (Apple silicon) |
|
macOS (Intel) |
|
Linux (64-bit) |
|
Linux (ARM 64-bit) |
|
Remember where you put the program; you need its full path in the next step.
One file for Claude Desktop: every release also has an .mcpb bundle per system, for example fieldpuppet-windows-x86_64.mcpb. Claude Desktop can install such a bundle from its Extensions settings, with no config file to edit.
Building from source instead needs Rust: cargo install --path .
Connect it to Claude Desktop
Open Claude Desktop. From the Claude menu in the menu bar choose Settings…, open the Developer tab and click Edit Config. This opens a file called
claude_desktop_config.json.Add the simulator to it, using the full path to the program you downloaded.
Windows:
{ "mcpServers": { "fieldpuppet": { "command": "C:\\Tools\\fieldpuppet.exe", "args": ["mcp"] } } }macOS and Linux:
{ "mcpServers": { "fieldpuppet": { "command": "/Users/you/tools/fieldpuppet", "args": ["mcp"] } } }If the file already lists other servers, add
"fieldpuppet": { ... }next to them insidemcpServers.Save the file, then quit Claude Desktop completely and open it again.
Start a new chat and try: "List the Modbus device templates you can simulate."
Claude Desktop starts the simulator when it opens and stops it when it closes, so the simulated devices exist only while Claude Desktop is running.
On macOS the first start may be blocked because the file was downloaded from the internet. Allow it once under System Settings → Privacy & Security.
Other MCP clients
The simulator speaks MCP over standard input and output, so any client that can start a local server works. For Claude Code:
claude mcp add fieldpuppet -- /full/path/to/fieldpuppet mcpDashboard
While the simulator runs, open http://127.0.0.1:5080 in a browser. The page updates by itself and shows:
every running device with its address, and whether a scenario or fault is active on it;
the points of the selected device: current value, address, data type and how the value is changing;
the steps of its scenario and which of them have already run;
the most recent Modbus requests it received and how they were answered;
an activity feed listing, in order, everything that was changed: devices created, values set, scenarios started, faults injected and cleared.
The dashboard only displays; it cannot change anything. If port 5080 is taken the next free port is used, and asking the assistant "where is the dashboard?" gives the address. Start with --no-ui to switch it off.
Things to ask
"Create an energy meter and a pump. Which addresses do I connect to?"
"Set up 50 energy meters starting at port 6000."
"Make the tank level rise from 20 % to 95 % over two minutes, then switch the high level alarm on."
"Pump 2 should answer with a 'device busy' exception for the next 30 seconds."
"Which registers has my SCADA been reading from the drive in the last minute?"
"Here is the register list from a device manual. Build a simulated device that matches it."
"Save this setup as
water-stationso I can load it again tomorrow."
Then point your own software at 127.0.0.1 and the port the assistant reports.
Try it with PLCGateway
fieldpuppet works with any Modbus TCP client. If you use PLCGateway, add a Modbus TCP device with host 127.0.0.1, the port the assistant reported and unit id 1, and the simulated values show up like those of a real device. A 30-day trial is available on the website.
Use it without AI
Describe the devices in a YAML file and run it:
fieldpuppet run examples/water-station.yamldevices:
- id: pump-1
template: pump
port: 5020
- id: dosing-skid
port: 5021
points:
- name: chlorine_ppm
table: input
address: 0
scale: 0.01
unit: ppm
value: 0.8
signal: { type: random_walk, min: 0.5, max: 1.2, step: 0.02 }examples/water-station.yaml shows scenarios, shared ports and strict mode. fieldpuppet templates lists the built-in templates and their points.
Reference
Addresses
Addresses are zero-based protocol addresses: holding register 40001 is address 0. Function codes 1, 2, 3, 4, 5, 6, 15 and 16 are supported.
Table | Read with | Written with |
| 01 | 05, 15 |
| 02 | – |
| 03 | 06, 16 |
| 04 | – |
Points
Field | Meaning |
| Name used in tools and scenarios |
|
|
| Zero-based address |
|
|
|
|
| Engineering value = raw value × scale. Default |
| Free text |
| Starting value, in engineering units |
| Optional, see below |
Without strict: true on the device, addresses that no point covers read as zero and accept writes. With it, they answer illegal data address.
Signals
Type | Fields | Behaviour |
|
| Holds one value |
|
| Straight line; starts over unless |
|
| Sine wave |
|
| New random value every update |
|
| Drifts by at most |
|
| Counts up; optional wrap to zero |
|
| Alternates, half a period each |
Signals are evaluated every 200 ms (--tick-ms). A value written by a Modbus client stays until a signal on the same point overwrites it.
Faults
Type | Fields | What the client sees |
|
| Correct answers, late |
| – | A timeout |
|
| A Modbus exception (4 = device failure, 6 = busy, …) |
| – | The connection closes on every request |
Add duration_s to any of them to have it clear itself.
Scenario steps
Each step has at_s (seconds after the scenario starts) and an action:
Action | Fields |
|
|
|
|
|
|
|
|
| – |
Set repeat: true on the scenario to loop it.
MCP tools
list_templates, create_device, clone_device, list_devices, get_device, remove_device, remove_all_devices, read_points, set_point, set_signal, add_point, remove_point, read_registers, write_registers, apply_scenario, stop_scenario, inject_fault, clear_fault, get_traffic_log, save_project, load_project, list_projects.
Both the current MCP revision (2026-07-28) and the earlier handshake-based revisions are supported.
Command-line options
Option | Default | Meaning |
|
| Address to listen on. |
|
| First port given to devices that do not ask for one |
|
| Upper limit on running devices |
|
| How often signals update |
|
| Where |
|
| Port of the web dashboard |
| – | Do not start the dashboard |
| – | Project file to load at startup |
Options go after the command, for example "args": ["mcp", "--base-port", "6000"].
Safety notes
By default the simulator listens on this computer only. Use
--bind 0.0.0.0only on a network where nobody could mistake a simulated device for a real one.Port 502, the standard Modbus port, needs administrator rights on Linux and macOS. The default range starting at 5020 does not.
Modbus has no authentication. Anyone who can reach a simulated device can read and write it.
The dashboard has no login either. It listens on the same address as the devices and is read-only.
Limits in this version
Modbus TCP only; no serial RTU or ASCII.
Devices do not model process behaviour on their own. A pump does not stop because its run coil was cleared; a scenario or the assistant has to change the values.
State lives in memory. Save a project to keep it.
Development
cargo test # unit tests
cargo build --release
python3 tests/e2e.py target/release/fieldpuppet # end-to-end: MCP calls plus real Modbus requestsLicense
Licensed under either of the Apache License, Version 2.0 or the MIT license, at your option.
Available Tools
22 toolsadd_pointAdd a point to a deviceA
Add one new named point (a coil, discrete input or register value) to a device that is already running, without restarting it or disturbing connected clients. Use it to extend a template device; to define points when a device is first created, pass them to create_device instead. The point takes its initial value, or starts its signal, immediately. Returns the new point with its current value. Fails if the device does not exist, the name is already used on that device, or the definition is invalid (for example a 32-bit type in a bit table).
Inputs: point (required), device_id (required).
apply_scenarioPlay a scenario on a deviceA
Play a timeline of timed steps on one device, starting now: set values, start or stop signals, inject or clear faults at given seconds. Use it to rehearse a sequence such as a pump trip followed by recovery; use set_point, set_signal or inject_fault for a single immediate change. Replaces any scenario already running on that device. Values, signals and faults set by steps stay in place after the scenario ends. Returns the scenario state.
Inputs: scenario (required), device_id (required).
clear_faultClear a device's faultAIdempotent
Remove the active communication fault from one device so it answers Modbus requests normally again. Use it to end a fault started by inject_fault or by a scenario step before its duration runs out. It does not stop a running scenario, which may inject a fault again at a later step (use stop_scenario for that), and it does not change any values. Safe to call when no fault is active. Returns 'cleared': true if a fault was removed, false if there was none. Fails if the device does not exist.
Inputs: device_id (required).
clone_deviceClone a device many timesA
Create several copies of a running device, each on its own port, for example 50 identical meters for a load test. Copies start with the source's points, current values, signals and settings; later changes to the source do not reach them. Use create_device for a single new device. If a copy cannot be created the call stops there and the error says how many were made; those copies keep running. Returns the id, port and unit id of every copy.
Inputs: count (required), source_id (required), id_prefix, start_port.
create_deviceCreate a simulated deviceA
Start one simulated Modbus TCP device that real client software can connect to. Use clone_device instead when you need many copies of a device that already exists, and load_project to bring back a saved set. Without a port the device gets the next free port; give a port already used by this simulator together with a different unit_id to put several devices behind one port. Fails if the id is taken, the port is used by another program, or the device limit is reached. Returns the device id plus the host, port and unit id to connect to.
Inputs: id, name, port, points, +4 more.
get_deviceShow one device in fullARead-onlyIdempotent
Return everything about one device: connection details, settings, active fault, scenario progress and every point with its address, data type and current value. Use read_points instead when you only need values. Changes nothing. Fails if the id is unknown.
Inputs: device_id (required).
get_traffic_logShow recent Modbus requestsARead-onlyIdempotent
Show the most recent Modbus requests a device received from client software, oldest first: function code, address, quantity and how it was answered, plus the total number of requests served. Use it to see what the software under test is polling or to confirm a fault took effect. The log keeps the last 500 requests per device and is lost when the device is removed. Changes nothing.
Inputs: device_id (required), limit.
inject_faultInject a communication faultAIdempotent
Make one device misbehave on the wire so you can test how client software copes: slow answers, no answer (timeout), Modbus exception replies, or dropped connections. The fault applies to every request the device receives, replaces any fault already active on it, and lasts until clear_fault is called or its optional duration_s runs out. Point values keep updating in the background. Use apply_scenario to schedule faults at set times.
Inputs: fault (required), device_id (required).
list_devicesList running devicesARead-onlyIdempotent
List every running device with its id, host, port, unit id, active fault and scenario state, plus the dashboard address. Use it to find device ids or to check what is running; use get_device for one device's points and values. Changes nothing.
Inputs: no named parameters.
list_projectsList saved projectsARead-onlyIdempotent
List the names of the projects saved with save_project, sorted alphabetically, and the directory they are stored in. Use it to find a name for load_project or to check whether a name is taken before save_project overwrites it. Shows names only; load a project to see its devices. Changes nothing and returns an empty list when nothing has been saved.
Inputs: no named parameters.
list_templatesList device templatesARead-onlyIdempotent
List the built-in device templates (generic, energy_meter, vfd, temperature_controller, pump, tank) with every point each one provides: name, table, address, data type and unit. Call this before create_device to choose a template or to learn point names. Changes nothing.
Inputs: no named parameters.
load_projectLoad a saved projectADestructive
Start the devices stored in a project saved earlier with save_project, on the ports recorded in it. By default they are added next to the devices already running, and the call fails part-way if an id or port is already in use (devices started before the failure keep running). With replace true, all running devices are removed first, which discards their unsaved state. Call list_projects to see the available names. Returns the devices that were started.
Inputs: name (required), replace.
read_pointsRead point valuesARead-onlyIdempotent
Read the current engineering values (after scaling) of a device's points, with their units. Use this to check what a device is reporting right now; use read_registers when you need the raw 16-bit words a Modbus client would receive. Changes nothing. Fails if the device or a named point does not exist.
Inputs: device_id (required), points.
read_registersRead raw Modbus valuesARead-onlyIdempotent
Read raw values straight from one Modbus table of a device, exactly as a client would receive them: 0 or 1 for coil and discrete, unscaled 16-bit words (0-65535) for holding and input. Use it to verify byte order, scaling or addresses; use read_points for engineering values by name. Addresses no point covers read 0, even on strict devices. Changes nothing and is not recorded in the traffic log. Returns the table, start address and list of values.
Inputs: table (required), address (required), quantity (required), device_id (required).
remove_all_devicesRemove every deviceADestructiveIdempotent
Stop every running device and free all their ports. All points, values, traffic logs and scenarios are discarded; saved project files are not touched. Use it to start from a clean state, and call save_project first if the current setup should be kept. Returns how many devices were removed (0 if none were running).
Inputs: no named parameters.
remove_deviceRemove one deviceADestructive
Stop one device and free its port. Its points, values, traffic log and running scenario are discarded and Modbus clients can no longer reach it. This cannot be undone unless the device was saved with save_project. Use remove_all_devices to clear everything. Fails if the id is unknown.
Inputs: device_id (required).
remove_pointRemove a point from a deviceADestructive
Delete one named point from a running device, together with any signal on it. Only the definition is removed: the raw value last stored at its address stays readable by Modbus clients until overwritten (or is rejected if the device is strict and no other point covers the address). The device and its other points keep running. Use remove_device to remove the whole device. Fails if the device or point does not exist.
Inputs: point (required), device_id (required).
save_projectSave devices to a projectADestructiveIdempotent
Save every running device (points, current values, signals, ports, running scenarios) to a named project file on this machine so the same setup can be restored later with load_project. An existing project with the same name is overwritten without warning; call list_projects first to check. Running devices are not affected. Traffic logs and active faults are not saved. Fails if no devices are running. Returns the file path and device count.
Inputs: name (required).
set_pointSet a point to a fixed valueAIdempotent
Set one point to a fixed engineering value (the simulator applies the point's scale and data type). Any signal running on that point is stopped, so the value stays until changed again. Use set_signal for a value that changes over time and write_registers to write raw words at an address. Returns the point with its new value. Fails if the device or point does not exist.
Inputs: point (required), value (required), device_id (required).
set_signalMake a point change over timeAIdempotent
Attach a signal to one point so its value changes by itself: sine, ramp, random, random walk, counter, square or constant. It replaces any signal already on that point and runs until replaced, stopped, or overwritten by set_point. Pass signal null to stop the signal and keep the current value. Use set_point for a fixed value and apply_scenario to change several things on a timeline. Returns the point with its current value.
Inputs: point (required), signal (required), device_id (required).
stop_scenarioStop a device's scenarioAIdempotent
Stop the scenario running on one device so no further steps are played. Nothing is rolled back: values, signals and faults stay as the scenario left them (use clear_fault or set_point to reset them). Safe to call when no scenario is running. Fails if the device does not exist.
Inputs: device_id (required).
write_registersWrite raw Modbus valuesAIdempotent
Write raw values into one Modbus table of a device, starting at an address: 0-65535 for holding and input registers, 0 or 1 for coils and discrete inputs. Unlike a Modbus client this can also write the read-only tables (discrete, input), which is how you fake sensor inputs at an address no point covers. Use set_point when the address belongs to a named point and you want scaling applied; a signal running on a point at that address will overwrite the value on its next update. Returns how many values were written.
Inputs: table (required), values (required), address (required), device_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Every tool targets a distinct resource+action, and the descriptions explicitly cross-reference the near neighbors (read_points vs read_registers vs get_device, set_point vs set_signal vs write_registers, remove_device vs remove_all_devices). Removal/stop variants (remove_device, remove_all_devices, remove_point, stop_scenario, clear_fault) each have clear, non-overlapping semantics. An agent can reliably pick the right tool.
All names are snake_case verb_noun (list_templates, create_device, read_points, set_signal, inject_fault, save_project, load_project). Verbs are used consistently per action (list_*, get_*, remove_*, read_*/write_*, set_*), with no camelCase or style mixing.
22 tools is on the heavy side, but the simulator genuinely spans devices, points, signals, raw registers, faults, scenarios, traffic logs and projects. Each tool maps to a needed operation rather than redundant variants. Slightly over the ideal range but well-justified.
Coverage is broad: full device lifecycle (create/clone/list/get/remove/save/load/list_projects), point add/remove/set/signal/read, raw register read/write, fault inject/clear, scenario apply/stop, and traffic log. Minor gap: no update_point to change a point's scale/unit/definition without removing and re-adding it. Core workflows are otherwise complete.
Maintenance
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
AI-native mock API server with MCP. Create REST/SOAP mocks from Claude, Cursor, or Windsurf.
Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that standardizes and contextualizes industrial Modbus data.26MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Modbus TCP devices that enables AI agents to read/write PLC registers by name using YAML device profiles, with a built-in simulator.2MIT
- FlicenseNot gradedqualityCmaintenanceMCP server that connects AI assistants to Siemens TIA Portal via the Openness API. AI-assisted PLC programming, project management, hardware configuration, cross-reference analysis, and deployment. 19 tools, 230 actions.64-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets AI models read and control industrial devices via standardized protocols like Modbus, OPC UA, and MQTT, with simulation and real hardware modes.5MIT