# io.github.ctrlpi/ctrlpi-mcp (npm · ctrlpi-mcp)

MCP server to control Raspberry Pi, Pico W and ESP32 GPIO agents from an AI assistant.

- Trust score: 68/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-21

## Components

- npm · `ctrlpi-mcp`: 68/100 (this document), [markdown](https://verifymcp.io/servers/ctrlpi-ctrlpi-mcp/ctrlpi-mcp.md), [page](https://verifymcp.io/servers/ctrlpi-ctrlpi-mcp/ctrlpi-mcp)

## Channel facts

- Registry: `npm`
- Package: `ctrlpi-mcp`
- Version: `0.9.41`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-21.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - No production dependencies, so there is no dependency health to assess.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 2 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 67/100
  - AI-judged instruction clarity (good).
  - Tool/resource definitions use about 1878 tokens (~104/item across 18 items; 18 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 13/100
  - Stability observed for 4 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 67/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 0% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 18 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 18 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the io.github.ctrlpi/ctrlpi-mcp server?

io.github.ctrlpi/ctrlpi-mcp runs locally as an npm package, launched with npx -y ctrlpi-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add ctrlpi-ctrlpi-mcp -- npx -y ctrlpi-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "ctrlpi-ctrlpi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ctrlpi-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "ctrlpi-ctrlpi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ctrlpi-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add ctrlpi-ctrlpi-mcp -- npx -y ctrlpi-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ctrlpi-ctrlpi-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "ctrlpi-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add ctrlpi-ctrlpi-mcp --command npx --arg -y --arg ctrlpi-mcp
```

### Hermes

```yaml
mcp_servers:
  ctrlpi-ctrlpi-mcp:
    command: "npx"
    args: ["-y", "ctrlpi-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "ctrlpi-ctrlpi-mcp": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "ctrlpi-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add ctrlpi-ctrlpi-mcp -t stdio -c npx -a -y ctrlpi-mcp
```

### Other

```json
{
  "mcpServers": {
    "ctrlpi-ctrlpi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ctrlpi-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-20 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 7 to 10. That category is still filling its 30-day observation window: 2 days of observed history at the previous scan, 3 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-19 (score 67, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-11-18 (score 52, +1)

- [security improvement] Malware scan: unverified → pass
- [functional improvement] Stability: unverified → 0.03
- [functional] Package version: 0.9.40 → 0.9.41

### 2026-11-17 (score 51)

First indexed and scored.

## MCP tools (18)

### `mcp_agents_list` (~161 tokens)

List agents

List configured agents (Pi, Pico or ESP32). Returns name, ip, port, online (live /hello probe), type (pi/pico/esp32), version, has_default_key, and last_updated_at (UTC "YYYY-MM-DD HH:MM:SS", when the agent list was last saved; every sweep saves it). Unreachable agents are included (online=false). The LAN is swept automatically every hour. Pass rescan=true to sweep it now, but only when the user asks to find new hardware: a sweep takes 10 seconds or more. If has_default_key is true for any agent, tell the user that agent is on the insecure default key and ask whether to change it.

Input parameters:

- `rescan` (boolean)

### `mcp_gpio_read` (~49 tokens)

Read a pin

Read a GPIO pin value on `agent` by number or name, or 'all' to read all pins.

Input parameters:

- `agent` (string, required)
- `name_or_gpio` (string, required)

### `mcp_gpio_write` (~127 tokens)

Write a pin

Write a value to a GPIO pin on `agent` ('0', '1', 'on', 'off', or 'toggle'). Optional duration in seconds, after which the pin reverts to its previous state. If the pin has a configured 'max' pulse duration, the effective duration is clamped to it - and if no duration is given but 'max' is set, 'max' is used as the duration automatically.

Input parameters:

- `agent` (string, required)
- `duration` (number)
- `name_or_gpio` (string, required)
- `value` (string, required)

### `mcp_gpio_scan` (~122 tokens)

Scan all pins

Scan all hardware GPIO pins on `agent` and return each pin's level (the physical state), type, pull resistor and name; a reversed pin also reports `value` (its logical state) and `reversed`. Pins: BCM 2-27 on a Raspberry Pi, GP0-GP28 (minus the WiFi-reserved GP23/24/25/29) on a Pico, and every usable pin of the chip on an ESP32 (flash, PSRAM and USB pins are left out).

Input parameters:

- `agent` (string, required)

### `mcp_gpio_config` (~156 tokens)

Configure a pin

Configure a GPIO pin on `agent` by number. type: input/output/vcc/gnd/remove. init: 0/1/last. pullup: up/down/none (input only). max: max pulse duration in seconds (output only). reversed: active-low logic (input/output only). watched: trigger webhook on state change (logged on the agent if no notifications.webhook is configured).

Input parameters:

- `agent` (string, required)
- `gpio` (string, required)
- `init` (string)
- `max` (number)
- `name` (string)
- `pullup` (string)
- `reversed` (boolean)
- `type` (string)
- `watched` (boolean)

### `mcp_gpio_watched` (~37 tokens)

List watched pins

List the GPIO pins that are currently being actively watched (the ones emitting hardware interrupts/webhooks).

Input parameters:

- `agent` (string, required)

### `mcp_sensor_config` (~138 tokens)

Configure a sensor

Configure a named sensor on `agent`. A sensor runs a script and its output is the reading. `script` is "<script-file> [args...]": a bare filename in the agent's scripts/ folder (no paths - that folder is the only allowed location), with letters/digits-only arguments. On a Raspberry Pi it is a shell script run with `sh`; on a Pico or ESP32 a .py file the agent execs in-process. Pass remove=true to delete the sensor.

Input parameters:

- `agent` (string, required)
- `name` (string, required)
- `remove` (boolean)
- `script` (string)

### `mcp_sensor_read` (~104 tokens)

Read sensors

Read sensors on `agent`. With no `name`, reads every configured sensor and returns them merged into one JSON object; with a `name`, reads just that sensor. Every reading is nested under its sensor's own name: a script emitting a JSON object with several fields nests whole, one emitting a single-field object contributes just that field's value, and any other output is wrapped the same way.

Input parameters:

- `agent` (string, required)
- `name` (string)

### `mcp_script_list` (~89 tokens)

List scripts

List the files in `agent`'s scripts/ folder (the folder sensors run from): `scripts` ([{name, size, modified}]) and `write`: "enabled", "default_key" (writes are refused until the agent's api_key is changed from the default) or "locked" (a write.lock file there blocks every write).

Input parameters:

- `agent` (string, required)

### `mcp_script_read` (~43 tokens)

Read a script

Read one file from `agent`'s scripts/ folder. Returns {name, content}.

Input parameters:

- `agent` (string, required)
- `name` (string, required)

### `mcp_script_write` (~179 tokens)

Write or delete a script

Create or overwrite a file in `agent`'s scripts/ folder with `content`, or delete it with remove=true. `name` is a bare filename of up to 32 characters (letters, digits, . _ -, no leading dot or dash, no paths). Refused while the agent still has the default api_key, and once a write.lock file is in the folder. Writing write.lock (any content) locks every script write, and this tool can then no longer change or remove it. The lock does not stop runs: a script run with mcp_script_run that deletes files can remove write.lock, as can a shell (Pi) or USB (Pico, ESP32).

Input parameters:

- `agent` (string, required)
- `content` (string)
- `name` (string, required)
- `remove` (boolean)

### `mcp_script_run` (~141 tokens)

Run a script

Run a file from `agent`'s scripts/ folder and return {name, exit_code, output}. On a Raspberry Pi a .py runs with the agent's Python and anything else with `sh`; output is its stdout (first 2 KB) and a run over 15 s is killed. On a Pico or ESP32 the file is exec'd in-process: output is what its read(*args) returns, or its `result`, and exit_code is 1 if it raised. `args` are letters and digits only.

Input parameters:

- `agent` (string, required)
- `args` (array)
- `name` (string, required)

### `mcp_config_read` (~107 tokens)

Read agent config

Read `agent`'s global application configuration, grouped: `notifications` (`webhook` + `webhook_key`), `bridges` (matter/homekit/homebridge callbacks), `settings` (docs_enabled, logs_enabled, log_days), `sensors`, and configured pins (`gpios`). The `agent` block (platform, os, ip, cpu_temperature, version) is computed live on every read and is not stored.

Input parameters:

- `agent` (string, required)

### `mcp_config_write` (~196 tokens)

Update agent config

Update `agent`'s global configuration dynamically. These are the ungrouped (root) field names; the agent routes each into its group (webhook_url -> notifications.webhook, webhook_key -> notifications.webhook_key, docs_enabled/logs_enabled/log_days -> settings), so a read afterwards shows them nested. log_days controls how long log entries are kept (0-30, clamped; 0 clears the log immediately and keeps only the last hour). docs_enabled is Pi-only. Changing api_key changes the agent's authentication key immediately, and also updates the local agents-config.json file to match automatically.

Input parameters:

- `agent` (string, required)
- `api_key` (string)
- `docs_enabled` (boolean)
- `log_days` (number)
- `logs_enabled` (boolean)
- `name` (string)
- `webhook_key` (string)
- `webhook_url` (string)

### `mcp_config_load` (~61 tokens)

Replace agent config

Load a full config onto `agent` from a dict (the agent saves a backup first). Pass an empty dict {} to reset all settings on the agent keeping only its API key.

Input parameters:

- `agent` (string, required)
- `config` (object, required)

### `mcp_agent_restart` (~65 tokens)

Restart or reboot an agent

Restart `agent`'s server process. Pass reboot=true to reboot the whole device instead (a Pi, Pico or ESP32); an agent running on a Mac ignores it and restarts the process.

Input parameters:

- `agent` (string, required)
- `reboot` (boolean)

### `mcp_agent_upgrade` (~70 tokens)

Upgrade an agent

Upgrade `agent` to the latest release, then restart it. A Pi runs `install.sh --upgrade` (re-downloads the release files and reinstalls dependencies); a Pico or ESP32 downloads the new files over WiFi, swaps them in and resets.

Input parameters:

- `agent` (string, required)

### `mcp_agent_logs` (~33 tokens)

Read agent log

Read the last 50 lines of `agent`'s server log file.

Input parameters:

- `agent` (string, required)

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/ctrlpi-ctrlpi-mcp/ctrlpi-mcp#diagnostics

## Score history

- 2026-11-21: 68
- 2026-11-20: 68
- 2026-11-19: 67
- 2026-11-18: 52
- 2026-11-17: 51

## Common questions

### What is the io.github.ctrlpi/ctrlpi-mcp server?

io.github.ctrlpi/ctrlpi-mcp is listed in the public MCP registry as io.github.ctrlpi/ctrlpi-mcp. MCP server to control Raspberry Pi, Pico W and ESP32 GPIO agents from an AI assistant. This page covers its npm package (ctrlpi-mcp).

### Is the io.github.ctrlpi/ctrlpi-mcp server safe to use?

io.github.ctrlpi/ctrlpi-mcp scores 68 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 November 2026. It declares no install or post-install scripts. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the io.github.ctrlpi/ctrlpi-mcp server expose?

io.github.ctrlpi/ctrlpi-mcp exposes 18 tools: mcp_agents_list, mcp_gpio_read, mcp_gpio_write, mcp_gpio_scan, mcp_gpio_config, and 13 more. Their descriptions and schemas cost roughly 1,878 tokens of context every time the server is loaded.

### Is the io.github.ctrlpi/ctrlpi-mcp server still maintained?

io.github.ctrlpi/ctrlpi-mcp is still listed as active in the MCP registry. We last reached this channel on 21 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the io.github.ctrlpi/ctrlpi-mcp server under?

io.github.ctrlpi/ctrlpi-mcp declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

### What did VerifyMCP test on the io.github.ctrlpi/ctrlpi-mcp server?

VerifyMCP ran 16 checks on io.github.ctrlpi/ctrlpi-mcp, covering Malware scan, Known CVEs, Install scripts, Dependency health and 12 more. Endpoint Security and Transport & Reachability do not apply to an npm package, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.

## Links

- npm package: https://www.npmjs.com/package/ctrlpi-mcp
- Socket report: https://socket.dev/npm/package/ctrlpi-mcp
- Repository: https://github.com/ctrlpi/ctrlpi-mcp
- Website: https://ctrlpi.com/ctrlpi-mcp
- Changelog RSS feed: https://verifymcp.io/servers/ctrlpi-ctrlpi-mcp/ctrlpi-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/ctrlpi-ctrlpi-mcp/ctrlpi-mcp/changelog.json
- Trust report (JSON): https://verifymcp.io/servers/ctrlpi-ctrlpi-mcp/ctrlpi-mcp.json
- HTML version of this page: https://verifymcp.io/servers/ctrlpi-ctrlpi-mcp/ctrlpi-mcp
