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

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

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

Actions:

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

Display

Keyboard Input

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

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

System

Usage Examples

Once configured, ask Claude to:

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

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

1. Verify NanoKVM is reachable: ping
2. Check web UI is accessible: http://
3. Verify credentials are correct

Authentication Failed

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

HID Input Not Working

1. Try nanokvm_reset_hid tool
2. Check “Reset HID” in NanoKVM web UI
3. Verify USB cable connection to target machine
4. Check /dev/hidg* devices exist on NanoKVM via SSH

Screenshot Timeout

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

License

MIT

Related Projects

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