AI导哈

NanoKVM远程控制服务器

NanoKVM MCP服务器是一个基于Model Context Protocol的远程控制工具，允许AI助手通过键盘、鼠标、电源按钮和屏幕捕获远程控制NanoKVM设备。

  • by scgreenhalgh
  • Python
  • 本地部署
  • 14 星标
  • 更新于
在 GitHub 查看 scgreenhalgh/nanokvm-mcp

使用说明

NanoKVM MCP服务器

用于控制的MCP（模型上下文协议）服务器 Sipeed NanoKVM 设备。这使得像克劳德这样的人工智能助手能够通过键盘、鼠标、电源按钮和屏幕截图远程控制硬件。

什么是NanoKVM？

NanoKVM 是一种基于RISC-V的开源、价格合理的IP-KVM设备。它允许在BIOS级别远程访问计算机，非常适合管理服务器、嵌入式系统或任何无头机器。

什么是MCP？

模型上下文协议 是将AI助手连接到外部工具和数据源的开放标准。该服务器将NanoKVM功能作为MCP工具公开，Claude和其他AI助手可以使用。

特性

类别 功能
功率控制 通过ATX顶盖打开/关闭电源、重置、强制关闭
键盘 键入文本，发送组合键（Ctrl+C、Alt+F4等）
鼠标/触摸 点击、移动、滚动、点击绝对屏幕坐标
截图 从MJPEG视频流中捕获JPEG格式的显示
ISO安装 装载/卸载ISO映像以进行远程操作系统安装
监控 电源LED状态、HDD活动、HDMI状态、分辨率

安装

来自源头

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

依赖项

  • Python 3.10+
  • mcp -模型上下文协议SDK
  • httpx -异步HTTP客户端
  • websockets -用于实时HID的WebSocket客户端
  • pycryptodome -AES加密用于身份验证
  • pillow -屏幕截图的图像处理

配置

环境变量

变量 必填 默认 描述
NANOKVM_HOST 是 - NanoKVM IP地址或主机名
NANOKVM_USER 没有 admin Web UI用户名
NANOKVM_PASS 没有 admin Web UI密码
NANOKVM_SCREEN_WIDTH 没有 1920 目标屏幕宽度（像素）
NANOKVM_SCREEN_HEIGHT 没有 1080 目标屏幕高度（像素）
NANOKVM_HTTPS 没有 false 使用HTTPS而不是HTTP

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %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 MCP配置中：

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

可用的MCP工具

功率控制

工具 参数 说明
nanokvm_power action: power, power_long, reset 控制电源按钮或重置
nanokvm_led_status - 获取电源和HDD LED状态

行动：

  • power -短按（800ms）-正常电源开/关
  • power_long -长按（5000ms）-强制断电
  • reset -按下重置按钮

显示

工具 参数 说明
nanokvm_hdmi_status - 获取HDMI连接状态和分辨率
nanokvm_hdmi_reset - 重置HDMI连接
nanokvm_screenshot - 以base64 JPEG格式捕获显示

键盘输入

工具 参数 说明
nanokvm_send_text text, language 键入文本（最多1024个字符）
nanokvm_send_key key, ctrl, shift, alt, meta 发送带有修饰符的单键

支持的密钥：

  • 信件： a-z
  • 数字： 0-9
  • 功能键： f1-f12
  • 导航： up, down, left, right, home, end, pageup, pagedown
  • 控制： enter, escape, tab, backspace, delete, insert, space

鼠标/触摸输入

工具 参数 说明
nanokvm_tap x, y 点击屏幕坐标
nanokvm_click button, x, y 点击按钮，可选位置
nanokvm_move x, y 将光标移动到位置
nanokvm_scroll amount 滚轮（正向=向下）

坐标系：

  • 原点（0,0）位于左上角
  • 坐标以屏幕像素为单位，基于 SCREEN_WIDTH 和 SCREEN_HEIGHT
  • 内部映射到NanoKVM的1-32767绝对坐标范围

存储

工具 参数 说明
nanokvm_list_images - 列出可用的ISO图像
nanokvm_mount_iso file, as_cdrom 安装ISO映像
nanokvm_unmount_iso - 卸载当前ISO
nanokvm_mounted_image - 获取挂载图像信息

系统

工具 参数 说明
nanokvm_reset_hid - 重置键盘/鼠标设备
nanokvm_info - 获取NanoKVM设备信息
nanokvm_hardware - 获取硬件信息

使用示例

配置后，让Claude：

请求 使用的工具
“服务器通电了吗？” nanokvm_led_status
“打开机器电源” nanokvm_power
“重置服务器” nanokvm_power 和 action="reset"
“强制关机” nanokvm_power 和 action="power_long"
键入“root”并按enter键 nanokvm_send_text + nanokvm_send_key
“按Ctrl+Alt+Delete” nanokvm_send_key 带有修饰语
“截图” nanokvm_screenshot
点击位置500300 nanokvm_click
“安装Ubuntu ISO” nanokvm_mount_iso

程序化使用

您也可以直接使用客户端库：

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 参考

看 API_REFERENCE.md 有关NanoKVM REST API和WebSocket协议的完整文档，包括：

  • 身份验证（AES-256-CBC加密）
  • 所有具有请求/响应格式的REST端点
  • 用于键盘和鼠标的WebSocket HID协议
  • USB HID按键代码参考
  • 通过直接SSH HID访问 /dev/hidg*

运作原理

建筑

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

沟通方法

特征 方法 端点
身份验证 REST POST /api/auth/login
电源控制 REST POST /api/vm/gpio
文本输入 REST POST /api/hid/paste
按键/鼠标事件 WebSocket /api/ws
截图 REST GET /api/stream/mjpeg （解析）
ISO挂载 REST POST /api/storage/image/mount

发展

设置

# 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

项目结构

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

故障排除

连接被拒绝

  1. 验证NanoKVM是否可访问： ping <NANOKVM_HOST>
  2. 检查web UI是否可访问： http://<NANOKVM_HOST>
  3. 验证凭据是否正确

认证失败

  1. 默认凭据为 admin/admin
  2. 检查NanoKVM web UI中的密码是否已更改
  3. 可以在中禁用身份验证 /etc/kvm/server.yaml

HID输入不工作

  1. 尝试 nanokvm_reset_hid 工具
  2. 检查NanoKVM web UI中的“重置HID”
  3. 验证USB电缆与目标计算机的连接
  4. 检查 /dev/hidg* 设备通过SSH存在于NanoKVM上

屏幕截图超时

  1. 确保HDMI已连接并检测到信号
  2. 检查 nanokvm_hdmi_status 用于连接状态
  3. 尝试 nanokvm_hdmi_reset 重新初始化

许可证

麻省理工学院

相关项目

相关 MCP