Skip to main content
Glama
fieldpuppet

fieldpuppet

Official

fieldpuppet

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)

fieldpuppet-windows-x86_64.zip

macOS (Apple silicon)

fieldpuppet-macos-aarch64.tar.gz

macOS (Intel)

fieldpuppet-macos-x86_64.tar.gz

Linux (64-bit)

fieldpuppet-linux-x86_64.tar.gz

Linux (ARM 64-bit)

fieldpuppet-linux-aarch64.tar.gz

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

  1. 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.

  2. 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 inside mcpServers.

  3. Save the file, then quit Claude Desktop completely and open it again.

  4. 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 mcp

Dashboard

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-station so 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.yaml
devices:
  - 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

coil

01

05, 15

discrete

02

–

holding

03

06, 16

input

04

–

Points

Field

Meaning

name

Name used in tools and scenarios

table

coil, discrete, holding or input

address

Zero-based address

data_type

u16 (default), i16, u32, i32, f32. 32-bit types take two registers, high word first.

word_swap

true to send the low word first

scale

Engineering value = raw value × scale. Default 1.

unit, description

Free text

value

Starting value, in engineering units

signal

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

constant

value

Holds one value

ramp

from, to, period_s, repeat

Straight line; starts over unless repeat: false

sine

min, max, period_s

Sine wave

random

min, max

New random value every update

random_walk

min, max, step

Drifts by at most step per update

counter

per_second, rollover

Counts up; optional wrap to zero

square

low, high, period_s

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

delay

ms

Correct answers, late

no_response

–

A timeout

exception

code

A Modbus exception (4 = device failure, 6 = busy, …)

disconnect

–

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_point

point, value

set_signal

point, signal

clear_signal

point

fault

fault

clear_fault

–

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

--bind

127.0.0.1

Address to listen on. 0.0.0.0 accepts connections from other machines.

--base-port

5020

First port given to devices that do not ask for one

--max-devices

1000

Upper limit on running devices

--tick-ms

200

How often signals update

--data-dir

~/.fieldpuppet/projects

Where save_project keeps its files

--ui-port

5080

Port of the web dashboard

--no-ui

–

Do not start the dashboard

--project (mcp only)

–

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.0 only 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 requests

License

Licensed under either of the Apache License, Version 2.0 or the MIT license, at your option.

Available Tools

22 tools
add_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 faultA
Idempotent

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 fullA
Read-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 requestsA
Read-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 faultA
Idempotent

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 devicesA
Read-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 projectsA
Read-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 templatesA
Read-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 projectA
Destructive

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 valuesA
Read-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 valuesA
Read-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 deviceA
DestructiveIdempotent

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 deviceA
Destructive

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 deviceA
Destructive

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 projectA
DestructiveIdempotent

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 valueA
Idempotent

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 timeA
Idempotent

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 scenarioA
Idempotent

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 valuesA
Idempotent

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

    A4.6/5.0

    Scored across 22 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers