ctrlpi-mcp · ctrlPi

What it is

The MCP protocol (JSON-RPC over stdio or Streamable HTTP) is hand-rolled on Node built-ins, no SDK, no node_modules, one file. The server holds no GPIO logic: every tool names an agent from its config.json and proxies the call to that agent's REST endpoints, forwarding the agent's own API key.

✨First run is hands-free: with no config.json present, the server scans your LAN's /24 for agents answering /hello, tries the default key, and writes its own config.

Connect Claude Desktop (stdio)

Claude Desktop launches the server itself, nothing needs to be running beforehand. Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "ctrlpi": {
      "command": "node",
      "args": ["/path/to/ctrlpi-mcp/server.js"]
    }
  }
}

Or over the network (Streamable HTTP)

Start the server with ./run.sh --http (add --host 0.0.0.0 if Claude runs on a different machine), then connect through mcp-remote with the server's top-level API key:

{
  "mcpServers": {
    "ctrlpi": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://your-host:8315/mcp",
        "--header", "Api-Key: your-mcp-key"
      ]
    }
  }
}

The tools

Tool	What it does
`mcp_agents_list`	List configured agents with live online status and type (pi/pico), pass `rescan` to sweep the LAN again
`mcp_gpio_read`	Read one pin or all pins of an agent
`mcp_gpio_write`	Write `0`/`1`/`flip`, with optional pulse duration
`mcp_gpio_scan`	Hardware scan of every pin, with physical levels
`mcp_gpio_config`	Configure a pin: type, name, pullup, init, max, reversed, watched
`mcp_config_read`	Read an agent's identity and full config
`mcp_config_write`	Update agent config fields
`mcp_config_load`	Replace an agent's whole config
`mcp_agent_restart`	Restart the agent process (or reboot the device)
`mcp_agent_logs`	Fetch the agent's recent log lines

Configuration

One small file maps names to agents; it's re-read on every access, so edits apply without a restart:

{
  "api_key": "your-mcp-key",          // gates HTTP mode only
  "agents": [
    { "name": "garage-pi", "ip": "192.168.1.50", "port": 8314, "api_key": "..." }
  ]
}

In the family

Drives any mix of raspberry-pi-gpio-api and pico-gpio-api agents. It's an inbound control plane only, real-time input events stay on the agents' webhook path to the bridges.