NanoKVM MCP Server

NanoKVM MCP服务器

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

什么是NanoKVM？

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

什么是MCP？

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

特性

安装

来自源头

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 -屏幕截图的图像处理

配置

环境变量

克劳德桌面版

添加 ~/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工具

功率控制

行动：

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

显示

键盘输入

支持的密钥：

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

鼠标/触摸输入

坐标系：

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

存储

系统

使用示例

配置后，让Claude：

程序化使用

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

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   │                  │  └───────────┘  │
└─────────────────┘                  └─────────────────┘

沟通方法

发展

设置

# 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
2. 检查web UI是否可访问： http://
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 重新初始化

许可证

麻省理工学院

相关项目

• Sipeed NanoKVM -此服务器控制的硬件
• 模型上下文协议 -协议规范
• FastMCP -Python MCP框架