README.md
Remotely control Sipeed NanoKVM hardware for BIOS-level management
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 SDKhttpx- Async HTTP clientwebsockets- WebSocket client for real-time HIDpycryptodome- AES encryption for authenticationpillow- 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/offpower_long- Long press (5000ms) - force power offreset- 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_WIDTHandSCREEN_HEIGHT - Internally mapped to NanoKVM's 1-32767 absolute coordinate range
Storage
| Tool | Parameters | Description |
Tools (11)
nanokvm_powerControl power button or resetnanokvm_led_statusGet power and HDD LED statesnanokvm_hdmi_statusGet HDMI connection state and resolutionnanokvm_hdmi_resetReset HDMI connectionnanokvm_screenshotCapture display as base64 JPEGnanokvm_send_textType text (max 1024 chars)nanokvm_send_keySend single key with modifiersnanokvm_tapTap at screen coordinatesnanokvm_clickClick button, optionally at positionnanokvm_moveMove cursor to positionnanokvm_scrollScroll wheel (positive=down)Environment Variables
NANOKVM_HOSTrequiredNanoKVM IP address or hostnameNANOKVM_USERWeb UI usernameNANOKVM_PASSWeb UI passwordNANOKVM_SCREEN_WIDTHTarget screen width in pixelsNANOKVM_SCREEN_HEIGHTTarget screen height in pixelsNANOKVM_HTTPSUse HTTPS instead of HTTPConfiguration
claude_desktop_config.json
{"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"}}}}Try it
→Check the current HDMI status and take a screenshot of the server display.
→Perform a hard reset on the server by holding the power button for 5 seconds.
→Type the BIOS password into the login field and press enter.
→Move the mouse to the center of the screen and click to wake the display.