NanoKVM MCP Server

An MCP (Model Context Protocol) server for controlling Sipeed NanoKVM devices. This enables AI assistants like Claude to remotely control hardware via keyboard, mouse, power buttons, and screen capture.

What is NanoKVM?

NanoKVM is an open-source, affordable IP-KVM device based on RISC-V. It allows remote access to computers at the BIOS level—perfect for managing servers, embedded systems, or any headless machine.

What is MCP?

Model Context Protocol is an open standard for connecting AI assistants to external tools and data sources. This server exposes NanoKVM functionality as MCP tools that Claude and other AI assistants can use.

Features

Category	Capabilities
Power Control	Power on/off, reset, force shutdown via ATX header
Keyboard	Type text, send key combinations (Ctrl+C, Alt+F4, etc.)
Mouse/Touch	Click, move, scroll, tap at absolute screen coordinates
Screenshots	Capture display as JPEG from MJPEG video stream
ISO Mounting	Mount/unmount ISO images for remote OS installation
Monitoring	Power LED status, HDD activity, HDMI state, resolution

Installation

From Source

git clone https://github.com/scgreenhalgh/nanokvm-mcp.git
cd nanokvm-mcp
pip install -e .

Dependencies

Python 3.10+
mcp - Model Context Protocol SDK
httpx - Async HTTP client
websockets - WebSocket client for real-time HID
pycryptodome - AES encryption for authentication
pillow - Image processing for screenshots

Configuration

Environment Variables

Variable	Required	Default	Description
`NANOKVM_HOST`	Yes	-	NanoKVM IP address or hostname
`NANOKVM_USER`	No	`admin`	Web UI username
`NANOKVM_PASS`	No	`admin`	Web UI password
`NANOKVM_SCREEN_WIDTH`	No	`1920`	Target screen width in pixels
`NANOKVM_SCREEN_HEIGHT`	No	`1080`	Target screen height in pixels
`NANOKVM_HTTPS`	No	`false`	Use HTTPS instead of HTTP

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "nanokvm": {
      "command": "python",
      "args": ["-m", "nanokvm_mcp.server"],
      "env": {
        "NANOKVM_HOST": "192.168.1.100",
        "NANOKVM_USER": "admin",
        "NANOKVM_PASS": "admin",
        "NANOKVM_SCREEN_WIDTH": "1920",
        "NANOKVM_SCREEN_HEIGHT": "1080"
      }
    }
  }
}

Claude Code

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "nanokvm": {
      "command": "python",
      "args": ["-m", "nanokvm_mcp.server"],
      "env": {
        "NANOKVM_HOST": "192.168.1.100"
      }
    }
  }
}

Available MCP Tools

Power Control

Tool	Parameters	Description
`nanokvm_power`	`action`: `power`, `power_long`, `reset`	Control power button or reset
`nanokvm_led_status`	-	Get power and HDD LED states

Actions:

power - Short press (800ms) - normal power on/off
power_long - Long press (5000ms) - force power off
reset - Press reset button

Display

Tool	Parameters	Description
`nanokvm_hdmi_status`	-	Get HDMI connection state and resolution
`nanokvm_hdmi_reset`	-	Reset HDMI connection
`nanokvm_screenshot`	-	Capture display as base64 JPEG

Keyboard Input

Tool	Parameters	Description
`nanokvm_send_text`	`text`, `language`	Type text (max 1024 chars)
`nanokvm_send_key`	`key`, `ctrl`, `shift`, `alt`, `meta`	Send single key with modifiers

Supported Keys:

Letters: a-z
Numbers: 0-9
Function keys: f1-f12
Navigation: up, down, left, right, home, end, pageup, pagedown
Control: enter, escape, tab, backspace, delete, insert, space

Mouse/Touch Input

Tool	Parameters	Description
`nanokvm_tap`	`x`, `y`	Tap at screen coordinates
`nanokvm_click`	`button`, `x`, `y`	Click button, optionally at position
`nanokvm_move`	`x`, `y`	Move cursor to position
`nanokvm_scroll`	`amount`	Scroll wheel (positive=down)

Coordinate System:

Origin (0, 0) is top-left corner
Coordinates are in screen pixels based on SCREEN_WIDTH and SCREEN_HEIGHT
Internally mapped to NanoKVM's 1-32767 absolute coordinate range

Storage

Tool	Parameters	Description
`nanokvm_list_images`	-	List available ISO images
`nanokvm_mount_iso`	`file`, `as_cdrom`	Mount ISO image
`nanokvm_unmount_iso`	-	Unmount current ISO
`nanokvm_mounted_image`	-	Get mounted image info

System

Tool	Parameters	Description
`nanokvm_reset_hid`	-	Reset keyboard/mouse devices
`nanokvm_info`	-	Get NanoKVM device info
`nanokvm_hardware`	-	Get hardware information

Usage Examples

Once configured, ask Claude to:

Request	Tool Used
"Is the server powered on?"	`nanokvm_led_status`
"Power on the machine"	`nanokvm_power`
"Reset the server"	`nanokvm_power` with `action="reset"`
"Force shutdown"	`nanokvm_power` with `action="power_long"`
"Type 'root' and press enter"	`nanokvm_send_text` + `nanokvm_send_key`
"Press Ctrl+Alt+Delete"	`nanokvm_send_key` with modifiers
"Take a screenshot"	`nanokvm_screenshot`
"Click at position 500, 300"	`nanokvm_click`
"Mount the Ubuntu ISO"	`nanokvm_mount_iso`

Programmatic Usage

You can also use the client library directly:

import asyncio
from nanokvm_mcp import NanoKVMClient

async def main():
    # Initialize client
    client = NanoKVMClient(
        host="192.168.1.100",
        username="admin",
        password="admin",
        screen_width=1920,
        screen_height=1080,
    )

    try:
        # Check power status
        status = await client.get_led_status()
        print(f"Power LED: {status['pwr']}, HDD LED: {status['hdd']}")

        # Get HDMI info
        hdmi = await client.get_hdmi_status()
        print(f"Resolution: {hdmi['width']}x{hdmi['height']}")

        # Type some text
        await client.paste_text("Hello, World!")

        # Send Enter key
        await client.send_key("enter")

        # Take a screenshot
        screenshot = await client.screenshot()
        with open("screenshot.jpg", "wb") as f:
            f.write(screenshot)

        # Click at coordinates
        await client.tap(500, 300)

        # Power cycle
        await client.reset()

    finally:
        await client.close()

asyncio.run(main())

API Reference

See API_REFERENCE.md for complete documentation of the NanoKVM REST API and WebSocket protocol, including:

Authentication (AES-256-CBC encryption)
All REST endpoints with request/response formats
WebSocket HID protocol for keyboard and mouse
USB HID keycodes reference
Direct SSH HID access via /dev/hidg*

How It Works

Architecture

┌─────────────────┐     HTTP/WS      ┌─────────────────┐
│   MCP Client    │◄────────────────►│    NanoKVM      │
│  (Claude, etc.) │                  │                 │
└────────┬────────┘                  │  ┌───────────┐  │
         │                           │  │ REST API  │  │
    MCP Protocol                     │  └───────────┘  │
         │                           │  ┌───────────┐  │
┌────────▼────────┐                  │  │ WebSocket │  │
│  nanokvm-mcp    │                  │  │   /api/ws │  │
│     Server      │                  │  └───────────┘  │
│                 │                  │  ┌───────────┐  │
│ • Power control │                  │  │   MJPEG   │  │
│ • HID input     │                  │  │  Stream   │  │
│ • Screenshots   │                  │  └───────────┘  │
└─────────────────┘                  └─────────────────┘

Communication Methods

Feature	Method	Endpoint
Authentication	REST	`POST /api/auth/login`
Power control	REST	`POST /api/vm/gpio`
Text input	REST	`POST /api/hid/paste`
Key/Mouse events	WebSocket	`/api/ws`
Screenshots	REST	`GET /api/stream/mjpeg` (parsed)
ISO mounting	REST	`POST /api/storage/image/mount`

Development

Setup

# Clone repository
git clone https://github.com/scgreenhalgh/nanokvm-mcp.git
cd nanokvm-mcp

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

Project Structure

nanokvm-mcp/
├── nanokvm_mcp/
│   ├── __init__.py      # Package exports
│   ├── server.py        # FastMCP server with tool definitions
│   ├── client.py        # NanoKVM API client (REST + WebSocket)
│   ├── auth.py          # AES password encryption
│   └── hid.py           # USB HID keycodes and helpers
├── pyproject.toml       # Package configuration
├── README.md            # This file
└── API_REFERENCE.md     # Complete API documentation

Troubleshooting

Connection Refused

Verify NanoKVM is reachable: ping <NANOKVM_HOST>
Check web UI is accessible: http://<NANOKVM_HOST>
Verify credentials are correct

Authentication Failed

Default credentials are admin/admin
Check if password was changed in NanoKVM web UI
Authentication can be disabled in /etc/kvm/server.yaml

HID Input Not Working

Try nanokvm_reset_hid tool
Check "Reset HID" in NanoKVM web UI
Verify USB cable connection to target machine
Check /dev/hidg* devices exist on NanoKVM via SSH

Screenshot Timeout

Ensure HDMI is connected and signal detected
Check nanokvm_hdmi_status for connection state
Try nanokvm_hdmi_reset to reinitialize

License

MIT

Sipeed NanoKVM - The hardware this server controls
Model Context Protocol - The protocol specification
FastMCP - Python MCP framework

NanoKVM MCP Server

What is NanoKVM?

NanoKVM is an open-source, affordable IP-KVM device based on RISC-V. It allows remote access to computers at the BIOS level—perfect for managing servers, embedded systems, or any headless machine.

What is MCP?

Features

Category	Capabilities
Power Control	Power on/off, reset, force shutdown via ATX header
Keyboard	Type text, send key combinations (Ctrl+C, Alt+F4, etc.)
Mouse/Touch	Click, move, scroll, tap at absolute screen coordinates
Screenshots	Capture display as JPEG from MJPEG video stream
ISO Mounting	Mount/unmount ISO images for remote OS installation
Monitoring	Power LED status, HDD activity, HDMI state, resolution

Installation

From Source

git clone https://github.com/scgreenhalgh/nanokvm-mcp.git
cd nanokvm-mcp
pip install -e .

Dependencies

Python 3.10+
mcp - Model Context Protocol SDK
httpx - Async HTTP client
websockets - WebSocket client for real-time HID
pycryptodome - AES encryption for authentication
pillow - Image processing for screenshots

Configuration

Environment Variables

Variable	Required	Default	Description
`NANOKVM_HOST`	Yes	-	NanoKVM IP address or hostname
`NANOKVM_USER`	No	`admin`	Web UI username
`NANOKVM_PASS`	No	`admin`	Web UI password
`NANOKVM_SCREEN_WIDTH`	No	`1920`	Target screen width in pixels
`NANOKVM_SCREEN_HEIGHT`	No	`1080`	Target screen height in pixels
`NANOKVM_HTTPS`	No	`false`	Use HTTPS instead of HTTP

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "nanokvm": {
      "command": "python",
      "args": ["-m", "nanokvm_mcp.server"],
      "env": {
        "NANOKVM_HOST": "192.168.1.100",
        "NANOKVM_USER": "admin",
        "NANOKVM_PASS": "admin",
        "NANOKVM_SCREEN_WIDTH": "1920",
        "NANOKVM_SCREEN_HEIGHT": "1080"
      }
    }
  }
}

Claude Code

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "nanokvm": {
      "command": "python",
      "args": ["-m", "nanokvm_mcp.server"],
      "env": {
        "NANOKVM_HOST": "192.168.1.100"
      }
    }
  }
}

Available MCP Tools

Power Control

Tool	Parameters	Description
`nanokvm_power`	`action`: `power`, `power_long`, `reset`	Control power button or reset
`nanokvm_led_status`	-	Get power and HDD LED states

Actions:

power - Short press (800ms) - normal power on/off
power_long - Long press (5000ms) - force power off
reset - Press reset button

Display

Tool	Parameters	Description
`nanokvm_hdmi_status`	-	Get HDMI connection state and resolution
`nanokvm_hdmi_reset`	-	Reset HDMI connection
`nanokvm_screenshot`	-	Capture display as base64 JPEG

Keyboard Input

Tool	Parameters	Description
`nanokvm_send_text`	`text`, `language`	Type text (max 1024 chars)
`nanokvm_send_key`	`key`, `ctrl`, `shift`, `alt`, `meta`	Send single key with modifiers

Supported Keys:

Letters: a-z
Numbers: 0-9
Function keys: f1-f12
Navigation: up, down, left, right, home, end, pageup, pagedown
Control: enter, escape, tab, backspace, delete, insert, space

Mouse/Touch Input

Tool	Parameters	Description
`nanokvm_tap`	`x`, `y`	Tap at screen coordinates
`nanokvm_click`	`button`, `x`, `y`	Click button, optionally at position
`nanokvm_move`	`x`, `y`	Move cursor to position
`nanokvm_scroll`	`amount`	Scroll wheel (positive=down)

Coordinate System:

Origin (0, 0) is top-left corner
Coordinates are in screen pixels based on SCREEN_WIDTH and SCREEN_HEIGHT
Internally mapped to NanoKVM's 1-32767 absolute coordinate range

Storage

Tool	Parameters	Description
`nanokvm_list_images`	-	List available ISO images
`nanokvm_mount_iso`	`file`, `as_cdrom`	Mount ISO image
`nanokvm_unmount_iso`	-	Unmount current ISO
`nanokvm_mounted_image`	-	Get mounted image info

System

Tool	Parameters	Description
`nanokvm_reset_hid`	-	Reset keyboard/mouse devices
`nanokvm_info`	-	Get NanoKVM device info
`nanokvm_hardware`	-	Get hardware information

Usage Examples

Once configured, ask Claude to:

Request	Tool Used
"Is the server powered on?"	`nanokvm_led_status`
"Power on the machine"	`nanokvm_power`
"Reset the server"	`nanokvm_power` with `action="reset"`
"Force shutdown"	`nanokvm_power` with `action="power_long"`
"Type 'root' and press enter"	`nanokvm_send_text` + `nanokvm_send_key`
"Press Ctrl+Alt+Delete"	`nanokvm_send_key` with modifiers
"Take a screenshot"	`nanokvm_screenshot`
"Click at position 500, 300"	`nanokvm_click`
"Mount the Ubuntu ISO"	`nanokvm_mount_iso`

Programmatic Usage

You can also use the client library directly:

import asyncio
from nanokvm_mcp import NanoKVMClient

async def main():
    # Initialize client
    client = NanoKVMClient(
        host="192.168.1.100",
        username="admin",
        password="admin",
        screen_width=1920,
        screen_height=1080,
    )

    try:
        # Check power status
        status = await client.get_led_status()
        print(f"Power LED: {status['pwr']}, HDD LED: {status['hdd']}")

        # Get HDMI info
        hdmi = await client.get_hdmi_status()
        print(f"Resolution: {hdmi['width']}x{hdmi['height']}")

        # Type some text
        await client.paste_text("Hello, World!")

        # Send Enter key
        await client.send_key("enter")

        # Take a screenshot
        screenshot = await client.screenshot()
        with open("screenshot.jpg", "wb") as f:
            f.write(screenshot)

        # Click at coordinates
        await client.tap(500, 300)

        # Power cycle
        await client.reset()

    finally:
        await client.close()

asyncio.run(main())

API Reference

See API_REFERENCE.md for complete documentation of the NanoKVM REST API and WebSocket protocol, including:

Authentication (AES-256-CBC encryption)
All REST endpoints with request/response formats
WebSocket HID protocol for keyboard and mouse
USB HID keycodes reference
Direct SSH HID access via /dev/hidg*

How It Works

Architecture

┌─────────────────┐     HTTP/WS      ┌─────────────────┐
│   MCP Client    │◄────────────────►│    NanoKVM      │
│  (Claude, etc.) │                  │                 │
└────────┬────────┘                  │  ┌───────────┐  │
         │                           │  │ REST API  │  │
    MCP Protocol                     │  └───────────┘  │
         │                           │  ┌───────────┐  │
┌────────▼────────┐                  │  │ WebSocket │  │
│  nanokvm-mcp    │                  │  │   /api/ws │  │
│     Server      │                  │  └───────────┘  │
│                 │                  │  ┌───────────┐  │
│ • Power control │                  │  │   MJPEG   │  │
│ • HID input     │                  │  │  Stream   │  │
│ • Screenshots   │                  │  └───────────┘  │
└─────────────────┘                  └─────────────────┘

Communication Methods

Feature	Method	Endpoint
Authentication	REST	`POST /api/auth/login`
Power control	REST	`POST /api/vm/gpio`
Text input	REST	`POST /api/hid/paste`
Key/Mouse events	WebSocket	`/api/ws`
Screenshots	REST	`GET /api/stream/mjpeg` (parsed)
ISO mounting	REST	`POST /api/storage/image/mount`

Development

Setup

# Clone repository
git clone https://github.com/scgreenhalgh/nanokvm-mcp.git
cd nanokvm-mcp

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

Project Structure

nanokvm-mcp/
├── nanokvm_mcp/
│   ├── __init__.py      # Package exports
│   ├── server.py        # FastMCP server with tool definitions
│   ├── client.py        # NanoKVM API client (REST + WebSocket)
│   ├── auth.py          # AES password encryption
│   └── hid.py           # USB HID keycodes and helpers
├── pyproject.toml       # Package configuration
├── README.md            # This file
└── API_REFERENCE.md     # Complete API documentation

Troubleshooting

Connection Refused

Verify NanoKVM is reachable: ping <NANOKVM_HOST>
Check web UI is accessible: http://<NANOKVM_HOST>
Verify credentials are correct

Authentication Failed

Default credentials are admin/admin
Check if password was changed in NanoKVM web UI
Authentication can be disabled in /etc/kvm/server.yaml

HID Input Not Working

Try nanokvm_reset_hid tool
Check "Reset HID" in NanoKVM web UI
Verify USB cable connection to target machine
Check /dev/hidg* devices exist on NanoKVM via SSH

Screenshot Timeout

Ensure HDMI is connected and signal detected
Check nanokvm_hdmi_status for connection state
Try nanokvm_hdmi_reset to reinitialize

License

MIT

Sipeed NanoKVM - The hardware this server controls
Model Context Protocol - The protocol specification
FastMCP - Python MCP framework

NanoKVM MCP Server

NanoKVM MCP Server

What is NanoKVM?

What is MCP?

Features

Installation

From Source

Dependencies

Configuration

Environment Variables

Claude Desktop

Claude Code

Available MCP Tools

Power Control

Display

Keyboard Input

Mouse/Touch Input

Storage

System

Usage Examples

Programmatic Usage

API Reference

How It Works

Architecture

Communication Methods

Development

Setup

Project Structure

Troubleshooting

Connection Refused

Authentication Failed

HID Input Not Working

Screenshot Timeout

License

Related Projects

NanoKVM MCP Server

What is NanoKVM?

What is MCP?

Features

Installation

From Source

Dependencies

Configuration

Environment Variables

Claude Desktop

Claude Code

Available MCP Tools

Power Control

Display

Keyboard Input

Mouse/Touch Input

Storage

System

Usage Examples

Programmatic Usage

API Reference

How It Works

Architecture

Communication Methods

Development

Setup

Project Structure

Troubleshooting

Connection Refused

Authentication Failed

HID Input Not Working

Screenshot Timeout

License

Related Projects