# fieldpuppet

> fieldpuppet is an open-source MCP server for industrial automation. Modbus TCP device simulator that an AI assistant can create and drive for testing. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Windows, Linux, Self-hosted
- **Repository:** https://github.com/cybriantops/fieldpuppet
- **MCP Registry name:** io.github.CybriantOps/fieldpuppet
- **Categories:** [industrial automation](https://ai-powered.com/categories/industrial-automation)
- **Listing updated:** 2026-11-21

## About

Run one small program and it can stand in for hundreds of Modbus TCP devices, each reachable on its own port or sharing a port under separate unit ids. Devices can be built from templates such as energy meters, drives, pumps and tanks, or defined point by point with signals that move over time in engineering units.

Through its built-in MCP server, an AI assistant can create devices, run timed scenarios, and inject faults like slow replies, missing answers, Modbus exceptions or dropped connections. A traffic log records which registers the client software polled and what it received, and a read-only web dashboard shows devices, values and activity.

It suits engineers testing SCADA systems, gateways, historians and HMIs who want to work without physical hardware. It only answers incoming requests and never connects to real equipment.

## Features

- **Many devices per process:** Each device gets its own port automatically, or several devices can share one port under different unit ids.
- **Templates and custom points:** Start from built-in templates for meters, drives, pumps and tanks, or define registers one by one.
- **Signals that change over time:** Sine, ramp, random, random walk, counter and square signals with scaling for 16-bit, 32-bit and float values.
- **Timed scenarios:** Schedule value changes, signals and faults per device on a timeline, optionally looping.
- **Communication fault injection:** Simulate delays, timeouts, Modbus exception codes and disconnects, with an optional duration.
- **Traffic log and dashboard:** Review polled registers and responses, and watch devices and activity in a live web page.

## Good for

- Testing a SCADA system against simulated pumps and meters without hardware
- Checking how a historian or gateway handles timeouts and exception replies
- Building a simulated device from a register list in a device manual
- Rehearsing alarm handling by ramping a tank level to a high threshold
- Reproducing a fault sequence on demand for integration tests

## Install

### Claude Code (Terminal)

```sh
claude mcp add fieldpuppet -- npx -y https://github.com/CybriantOps/fieldpuppet/releases/download/v0.1.2/fieldpuppet-linux-aarch64.mcpb
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "fieldpuppet": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/CybriantOps/fieldpuppet/releases/download/v0.1.2/fieldpuppet-linux-aarch64.mcpb"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "fieldpuppet": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/CybriantOps/fieldpuppet/releases/download/v0.1.2/fieldpuppet-linux-aarch64.mcpb"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "fieldpuppet": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/CybriantOps/fieldpuppet/releases/download/v0.1.2/fieldpuppet-linux-aarch64.mcpb"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "fieldpuppet": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/CybriantOps/fieldpuppet/releases/download/v0.1.2/fieldpuppet-linux-aarch64.mcpb"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "fieldpuppet": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/CybriantOps/fieldpuppet/releases/download/v0.1.2/fieldpuppet-linux-aarch64.mcpb"
      ]
    }
  }
}
```

## Tools

- `list_templates`: List available device templates.
- `create_device`: Create a simulated Modbus device.
- `clone_device`: Clone an existing device.
- `list_devices`: List running devices.
- `get_device`: Get details of a device.
- `remove_device`: Remove a device.
- `remove_all_devices`: Remove all devices.
- `read_points`: Read point values from a device.
- `set_point`: Set a point value.
- `set_signal`: Assign a signal to a point.
- `add_point`: Add a point to a device.
- `remove_point`: Remove a point from a device.
- `read_registers`: Read raw registers.
- `write_registers`: Write raw registers.
- `apply_scenario`: Start a timed scenario.
- `stop_scenario`: Stop a running scenario.
- `inject_fault`: Inject a communication fault.
- `clear_fault`: Clear an active fault.
- `get_traffic_log`: Show recent Modbus traffic.
- `save_project`: Save the current setup.
- `load_project`: Load a saved setup.
- `list_projects`: List saved setups.

## FAQ

### Does fieldpuppet connect to real equipment?

No. It only answers Modbus requests sent to it and never connects to real devices.

### Which Modbus function codes are supported?

Function codes 1, 2, 3, 4, 5, 6, 15 and 16 are supported, over Modbus TCP only.

### Does fieldpuppet work without an AI assistant?

Yes. Devices can be described in a YAML file and run from the command line.

### Is fieldpuppet secure to expose on a network?

By default it listens only on the local machine. Modbus has no authentication, so binding to all addresses should only be done on isolated networks.

### Is fieldpuppet free?

Yes. fieldpuppet is open source, so you can use and self-host it for free.

### How do I add fieldpuppet to Claude Code?

Run this command in your terminal: claude mcp add fieldpuppet -- npx -y https://github.com/CybriantOps/fieldpuppet/releases/download/v0.1.2/fieldpuppet-linux-aarch64.mcpb

### What are the best alternatives to fieldpuppet?

The closest alternatives to fieldpuppet are plctap, TiaCommander, OPC-UA MCP Server and OPC UA Modeler.

## Where this comes from

- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [plctap](https://ai-powered.com/mcp/plctap): plctap is an open-source MCP server for industrial automation.
- [TiaCommander](https://ai-powered.com/mcp/tiacommander): TiaCommander is a free MCP server for automotive.
- [OPC-UA MCP Server](https://ai-powered.com/mcp/opc-ua-mcp-server-2): OPC-UA MCP Server is an open-source MCP server for industrial automation.
- [OPC UA Modeler](https://ai-powered.com/mcp/opc-ua-modeler): OPC UA Modeler is a freemium MCP server for industrial automation.

---
Source: https://ai-powered.com/mcp/fieldpuppet
