NanoKVM PicoClaw MCP

An unofficial, self-hosted MCP adapter for the PicoClaw service installed by NanoKVM. It does not contain NanoKVM firmware and is not affiliated with Sipeed or TinyAGI.

The adapter proxies NanoKVM's native PicoClaw MCP handler instead of copying its screenshot and HID action semantics into another implementation. It also has explicit NanoKVM status, reboot, and macOS recovery-key tools.

Security boundary

Keep NanoKVM on a private network. Do not expose this stdio server directly to the Internet. If remote MCP access is needed, put an authenticated gateway such as GPTAdmin in front of one private relay instance.

The gateway machine is the only system that should hold device credentials and the SSH key. Other MCP clients should authenticate to that gateway, never to the NanoKVM itself.

The adapter requires a pinned known_hosts file for every SSH operation. It refuses unknown SSH host keys and disables agent/port forwarding.

Install

python3 -m pip install nanokvm-picoclaw-mcp

Set device-specific values in a mode-600 environment file owned by the relay service account. Do not put them in a repository or in command-line arguments.

export NANOKVM_URL='http://nanokvm.private.example'
export NANOKVM_USER='admin'
export NANOKVM_PASSWORD='set-in-a-secret-store'
export NANOKVM_SSH_HOST='nanokvm.private.example'
export NANOKVM_SSH_USER='root'
export NANOKVM_SSH_KEY='/secure/path/nanokvm_ed25519'
export NANOKVM_SSH_KNOWN_HOSTS='/secure/path/known_hosts_nanokvm'
nanokvm-picoclaw-mcp

The server exposes nanokvm_status, nanokvm_reboot, nanokvm_hold_recovery_keys, picoclaw_tools_list, picoclaw_tools_call, and picoclaw_chat. Treat reboot, recovery-key and dynamic PicoClaw calls as operator-only capabilities; a public gateway should enforce its own explicit authorization policy.

Development

python3 -m pip install -e '.[test]'
pytest -q

All tests are offline and use fake HTTP, WebSocket, and SSH transports.