docs(nanokvm): add MCP guides for Cube and PCIe (#1010)
BIN
docs/hardware/assets/NanoKVM/mcp/nanokvm-mcp-enabled-en.webp
Normal file
|
After Width: | Height: | Size: 16 KiB |
BIN
docs/hardware/assets/NanoKVM/mcp/nanokvm-mcp-enabled-zh.webp
Normal file
|
After Width: | Height: | Size: 15 KiB |
BIN
docs/hardware/assets/NanoKVM/mcp/nanokvm-mcp-entry-en.webp
Normal file
|
After Width: | Height: | Size: 14 KiB |
BIN
docs/hardware/assets/NanoKVM/mcp/nanokvm-mcp-entry-zh.webp
Normal file
|
After Width: | Height: | Size: 13 KiB |
BIN
docs/hardware/assets/NanoKVM/mcp/nanokvm-settings-page.webp
Normal file
|
After Width: | Height: | Size: 2.9 KiB |
BIN
docs/hardware/assets/NanoKVM/mcp/opencode-mcp-connected.webp
Normal file
|
After Width: | Height: | Size: 5.8 KiB |
|
After Width: | Height: | Size: 230 KiB |
|
After Width: | Height: | Size: 247 KiB |
236
docs/hardware/en/kvm/NanoKVM/mcp.md
Normal file
@@ -0,0 +1,236 @@
|
||||
---
|
||||
title: MCP Feature
|
||||
keywords: NanoKVM Cube, MCP, AI, Remote Control, KVM, OpenCode
|
||||
update:
|
||||
- date: 2026-08-19
|
||||
version: v0.1
|
||||
author: Liang Ziyue
|
||||
content:
|
||||
- Add NanoKVM Cube MCP guide
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
The MCP feature on NanoKVM Cube lets MCP-compatible AI tools connect to NanoKVM Cube, so the AI tool can view and control the target device through NanoKVM Cube.
|
||||
|
||||
After the connection is configured, the AI tool can use the target device screen content to assist with clicking, typing, opening applications, changing settings, troubleshooting issues, and performing repetitive operations. This feature is useful for remote maintenance, system configuration, troubleshooting, and assisted automation.
|
||||
|
||||
> The MCP feature gives the AI tool the ability to operate the target device. Use trusted AI tools only, and do not expose the MCP service on untrusted networks.
|
||||
|
||||
## How It Works
|
||||
|
||||
After MCP is enabled on NanoKVM Cube, the AI tool on the control device connects to the MCP service using the `Endpoint` and `API Key` shown on the NanoKVM Cube page. The AI tool does not connect to the target device directly. Instead, it gets screen content and sends control operations through NanoKVM Cube.
|
||||
|
||||
The connection flow is:
|
||||
|
||||
```text
|
||||
AI tool on the control device
|
||||
|
|
||||
| MCP
|
||||
v
|
||||
NanoKVM Cube
|
||||
|
|
||||
| KVM control
|
||||
v
|
||||
Target device
|
||||
```
|
||||
|
||||
In this flow:
|
||||
|
||||
+ The target device sends video to NanoKVM Cube through HDMI and receives keyboard and mouse control through the PC USB (HID) interface;
|
||||
+ NanoKVM Cube captures the target device screen and sends keyboard and mouse operations to the target device;
|
||||
+ The AI tool on the control device connects to NanoKVM Cube through MCP;
|
||||
+ After the user sends an instruction in the AI tool, the AI tool controls the target device through NanoKVM Cube.
|
||||
|
||||
## Preparation
|
||||
|
||||
Before using MCP, make sure that:
|
||||
|
||||
+ NanoKVM Cube is connected to the target device;
|
||||
+ The NanoKVM Cube web control page can display the target device screen correctly;
|
||||
+ NanoKVM Cube is connected to the network and has obtained an IP address;
|
||||
+ The control device can access the MCP endpoint shown by NanoKVM Cube;
|
||||
+ The control device has an MCP-compatible AI tool installed, such as [OpenCode](https://opencode.ai/download) or another MCP client;
|
||||
+ The NanoKVM Cube system and application versions support MCP.
|
||||
|
||||
> If the MCP option is not shown, check whether the NanoKVM Cube system and application have been updated to a version that supports MCP.
|
||||
|
||||
## Enable MCP
|
||||
|
||||
1. Connect NanoKVM Cube to the target device and confirm that the target device screen is displayed correctly.
|
||||
2. Enter the NanoKVM Cube IP address in a browser to open the NanoKVM Cube web control page.
|
||||
3. Log in to NanoKVM Cube.
|
||||
4. Open the settings page.
|
||||
|
||||

|
||||
|
||||
5. Find the MCP option.
|
||||
|
||||

|
||||
|
||||
6. Turn on the MCP switch.
|
||||
7. Record the `Endpoint` and `API Key` shown on the page.
|
||||
|
||||
## Add MCP to an AI Tool
|
||||
|
||||
Different AI tools use different MCP configuration methods. This section uses OpenCode as an example.
|
||||
|
||||
### Get the Endpoint and API Key
|
||||
|
||||
After MCP is enabled on NanoKVM Cube, the page shows an `Endpoint` and an `API Key`.
|
||||
|
||||

|
||||
|
||||
In this section:
|
||||
|
||||
+ `Endpoint` is the full URL of the NanoKVM Cube MCP server, for example `http://<NanoKVM-IP>/api/mcp` or `https://<NanoKVM-IP>/api/mcp`;
|
||||
+ `API Key` is the credential used to access the NanoKVM Cube MCP server.
|
||||
|
||||
When configuring an AI tool, copy the endpoint shown on the page directly. Do not split the IP address and port or change the protocol.
|
||||
|
||||
### Add MCP to OpenCode
|
||||
|
||||
OpenCode supports adding a remote MCP server through the global configuration file.
|
||||
|
||||
Create or edit the following configuration file:
|
||||
|
||||
```bash
|
||||
~/.config/opencode/opencode.json
|
||||
```
|
||||
|
||||
Configuration example:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"nanokvm": {
|
||||
"type": "remote",
|
||||
"url": "<Endpoint>",
|
||||
"oauth": false,
|
||||
"headers": {
|
||||
"Authorization": "Bearer <API-Key>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace:
|
||||
|
||||
+ `<Endpoint>` with the `Endpoint` shown on the NanoKVM Cube MCP page;
|
||||
+ `<API-Key>` with the `API Key` shown on the NanoKVM Cube MCP page.
|
||||
|
||||
The displayed endpoint may start with HTTP or HTTPS. Enter it exactly as shown. Use MCP only on a trusted LAN, and prefer HTTPS whenever possible.
|
||||
|
||||
If the endpoint starts with HTTPS and OpenCode cannot connect because of the local NanoKVM Cube certificate, set the following environment variable before starting OpenCode on Linux:
|
||||
|
||||
```bash
|
||||
export NODE_TLS_REJECT_UNAUTHORIZED=0
|
||||
opencode
|
||||
```
|
||||
|
||||
You can also start OpenCode with a single command:
|
||||
|
||||
```bash
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=0 opencode
|
||||
```
|
||||
|
||||
> The `NODE_TLS_REJECT_UNAUTHORIZED` environment variable disables TLS certificate verification for the current OpenCode process. Use it only when connecting to NanoKVM Cube MCP on a trusted LAN. Do not use it long term on untrusted networks.
|
||||
|
||||
After saving the configuration, restart OpenCode. Then check whether the MCP server is connected:
|
||||
|
||||
```bash
|
||||
opencode mcp list
|
||||
```
|
||||
|
||||
If an HTTPS endpoint produces a local certificate verification error, use:
|
||||
|
||||
```bash
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=0 opencode mcp list
|
||||
```
|
||||
|
||||
If `nanokvm` is shown as connected, OpenCode has successfully connected to NanoKVM Cube MCP.
|
||||
|
||||

|
||||
|
||||
After the connection succeeds, you can send an instruction to OpenCode and let OpenCode view and control the target device through NanoKVM Cube MCP.
|
||||
|
||||

|
||||
|
||||
To restore the default security behavior, close the current terminal and open a new one. You can also run:
|
||||
|
||||
```bash
|
||||
unset NODE_TLS_REJECT_UNAUTHORIZED
|
||||
```
|
||||
|
||||
### Other AI Tools
|
||||
|
||||
Other MCP-compatible AI tools can also try connecting to NanoKVM Cube MCP. Support for remote MCP, HTTPS, and tool-call permissions varies between tools and versions.
|
||||
|
||||
If an AI tool cannot handle the certificate used by an HTTPS endpoint, a reverse proxy such as Nginx may be required to handle certificates. This setup is more complex and is not recommended as the first choice for general users.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
After the connection succeeds, you can describe the operation you want to perform in natural language. For example:
|
||||
|
||||
```text
|
||||
Use NanoKVM Cube to check the current screen and tell me which page the target device is on.
|
||||
```
|
||||
|
||||
```text
|
||||
Use NanoKVM Cube to click the Settings button on the screen.
|
||||
```
|
||||
|
||||
```text
|
||||
Use NanoKVM Cube to open a terminal and type ifconfig to check the network information.
|
||||
```
|
||||
|
||||
```text
|
||||
Use NanoKVM Cube to continue the system installation process based on the current screen.
|
||||
```
|
||||
|
||||
Start with simple and easy-to-confirm operations, such as reading the screen, clicking a clear button, or typing a short command. For high-risk operations such as deleting files, formatting disks, or changing system configuration, confirm the action before allowing the AI tool to proceed.
|
||||
|
||||
## FAQ
|
||||
|
||||
### The AI Tool Cannot Connect to NanoKVM Cube MCP
|
||||
|
||||
Check:
|
||||
|
||||
+ Whether the NanoKVM Cube MCP switch is turned on;
|
||||
+ Whether the MCP endpoint is correct;
|
||||
+ Whether the `API Key` is correct;
|
||||
+ Whether the control device and NanoKVM Cube can reach each other over the network;
|
||||
+ When using an HTTPS endpoint, whether the AI tool can handle the local NanoKVM Cube certificate;
|
||||
+ Whether a firewall, router, VPN, or security software is blocking the connection;
|
||||
+ Whether NanoKVM Cube is connected to the network and shows an IP address.
|
||||
|
||||
### The AI Tool Can Connect to MCP, but Cannot Control the Target Device
|
||||
|
||||
Check:
|
||||
|
||||
+ Whether the NanoKVM Cube web control page can display the target device screen correctly;
|
||||
+ Whether the target device is connected to NanoKVM Cube correctly;
|
||||
+ Whether the current target device screen requires unlocking, login, or manual confirmation;
|
||||
+ Whether the AI tool allows MCP tool calls;
|
||||
+ Whether keyboard and mouse control works normally in NanoKVM Cube.
|
||||
|
||||
### The MCP Switch Is Not Shown
|
||||
|
||||
Check:
|
||||
|
||||
+ Whether the NanoKVM Cube system or application version is too old;
|
||||
+ Whether the current version supports MCP;
|
||||
+ Whether the KVM App needs to be updated from the web control page;
|
||||
+ Whether the settings page has been reopened after the update.
|
||||
|
||||
## Security Notes
|
||||
|
||||
+ MCP gives the AI tool the ability to operate the target device. Connect only trusted AI tools;
|
||||
+ Do not expose the MCP service directly to the public Internet;
|
||||
+ Do not expose the MCP endpoint on untrusted networks;
|
||||
+ Turn off MCP when it is not needed;
|
||||
+ Confirm the AI tool's action before operating important devices;
|
||||
+ Do not leak the NanoKVM Cube MCP `API Key`;
|
||||
+ When entering passwords, keys, tokens, or other sensitive information, make sure the AI tool and network environment are trusted.
|
||||
236
docs/hardware/en/kvm/NanoKVM_PCIe/mcp.md
Normal file
@@ -0,0 +1,236 @@
|
||||
---
|
||||
title: MCP Feature
|
||||
keywords: NanoKVM PCIe, MCP, AI, Remote Control, KVM, OpenCode
|
||||
update:
|
||||
- date: 2026-08-19
|
||||
version: v0.1
|
||||
author: Liang Ziyue
|
||||
content:
|
||||
- Add NanoKVM PCIe MCP guide
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
The MCP feature on NanoKVM PCIe lets MCP-compatible AI tools connect to NanoKVM PCIe, so the AI tool can view and control the target device through NanoKVM PCIe.
|
||||
|
||||
After the connection is configured, the AI tool can use the target device screen content to assist with clicking, typing, opening applications, changing settings, troubleshooting issues, and performing repetitive operations. This feature is useful for remote maintenance, system configuration, troubleshooting, and assisted automation.
|
||||
|
||||
> The MCP feature gives the AI tool the ability to operate the target device. Use trusted AI tools only, and do not expose the MCP service on untrusted networks.
|
||||
|
||||
## How It Works
|
||||
|
||||
After MCP is enabled on NanoKVM PCIe, the AI tool on the control device connects to the MCP service using the `Endpoint` and `API Key` shown on the NanoKVM PCIe page. The AI tool does not connect to the target device directly. Instead, it gets screen content and sends control operations through NanoKVM PCIe.
|
||||
|
||||
The connection flow is:
|
||||
|
||||
```text
|
||||
AI tool on the control device
|
||||
|
|
||||
| MCP
|
||||
v
|
||||
NanoKVM PCIe
|
||||
|
|
||||
| KVM control
|
||||
v
|
||||
Target device
|
||||
```
|
||||
|
||||
In this flow:
|
||||
|
||||
+ The target device sends video to NanoKVM PCIe through HDMI and receives keyboard and mouse control through the USB HID interface, which can use either a USB-C cable or the internal USB 2.0 header;
|
||||
+ NanoKVM PCIe captures the target device screen and sends keyboard and mouse operations to the target device;
|
||||
+ The AI tool on the control device connects to NanoKVM PCIe through MCP;
|
||||
+ After the user sends an instruction in the AI tool, the AI tool controls the target device through NanoKVM PCIe.
|
||||
|
||||
## Preparation
|
||||
|
||||
Before using MCP, make sure that:
|
||||
|
||||
+ NanoKVM PCIe is connected to the target device;
|
||||
+ The NanoKVM PCIe web control page can display the target device screen correctly;
|
||||
+ NanoKVM PCIe is connected to the network and has obtained an IP address;
|
||||
+ The control device can access the MCP endpoint shown by NanoKVM PCIe;
|
||||
+ The control device has an MCP-compatible AI tool installed, such as [OpenCode](https://opencode.ai/download) or another MCP client;
|
||||
+ The NanoKVM PCIe system and application versions support MCP.
|
||||
|
||||
> If the MCP option is not shown, check whether the NanoKVM PCIe system and application have been updated to a version that supports MCP.
|
||||
|
||||
## Enable MCP
|
||||
|
||||
1. Connect NanoKVM PCIe to the target device and confirm that the target device screen is displayed correctly.
|
||||
2. Enter the NanoKVM PCIe IP address in a browser to open the NanoKVM PCIe web control page.
|
||||
3. Log in to NanoKVM PCIe.
|
||||
4. Open the settings page.
|
||||
|
||||

|
||||
|
||||
5. Find the MCP option.
|
||||
|
||||

|
||||
|
||||
6. Turn on the MCP switch.
|
||||
7. Record the `Endpoint` and `API Key` shown on the page.
|
||||
|
||||
## Add MCP to an AI Tool
|
||||
|
||||
Different AI tools use different MCP configuration methods. This section uses OpenCode as an example.
|
||||
|
||||
### Get the Endpoint and API Key
|
||||
|
||||
After MCP is enabled on NanoKVM PCIe, the page shows an `Endpoint` and an `API Key`.
|
||||
|
||||

|
||||
|
||||
In this section:
|
||||
|
||||
+ `Endpoint` is the full URL of the NanoKVM PCIe MCP server, for example `http://<NanoKVM-IP>/api/mcp` or `https://<NanoKVM-IP>/api/mcp`;
|
||||
+ `API Key` is the credential used to access the NanoKVM PCIe MCP server.
|
||||
|
||||
When configuring an AI tool, copy the endpoint shown on the page directly. Do not split the IP address and port or change the protocol.
|
||||
|
||||
### Add MCP to OpenCode
|
||||
|
||||
OpenCode supports adding a remote MCP server through the global configuration file.
|
||||
|
||||
Create or edit the following configuration file:
|
||||
|
||||
```bash
|
||||
~/.config/opencode/opencode.json
|
||||
```
|
||||
|
||||
Configuration example:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"nanokvm": {
|
||||
"type": "remote",
|
||||
"url": "<Endpoint>",
|
||||
"oauth": false,
|
||||
"headers": {
|
||||
"Authorization": "Bearer <API-Key>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace:
|
||||
|
||||
+ `<Endpoint>` with the `Endpoint` shown on the NanoKVM PCIe MCP page;
|
||||
+ `<API-Key>` with the `API Key` shown on the NanoKVM PCIe MCP page.
|
||||
|
||||
The displayed endpoint may start with HTTP or HTTPS. Enter it exactly as shown. Use MCP only on a trusted LAN, and prefer HTTPS whenever possible.
|
||||
|
||||
If the endpoint starts with HTTPS and OpenCode cannot connect because of the local NanoKVM PCIe certificate, set the following environment variable before starting OpenCode on Linux:
|
||||
|
||||
```bash
|
||||
export NODE_TLS_REJECT_UNAUTHORIZED=0
|
||||
opencode
|
||||
```
|
||||
|
||||
You can also start OpenCode with a single command:
|
||||
|
||||
```bash
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=0 opencode
|
||||
```
|
||||
|
||||
> The `NODE_TLS_REJECT_UNAUTHORIZED` environment variable disables TLS certificate verification for the current OpenCode process. Use it only when connecting to NanoKVM PCIe MCP on a trusted LAN. Do not use it long term on untrusted networks.
|
||||
|
||||
After saving the configuration, restart OpenCode. Then check whether the MCP server is connected:
|
||||
|
||||
```bash
|
||||
opencode mcp list
|
||||
```
|
||||
|
||||
If an HTTPS endpoint produces a local certificate verification error, use:
|
||||
|
||||
```bash
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=0 opencode mcp list
|
||||
```
|
||||
|
||||
If `nanokvm` is shown as connected, OpenCode has successfully connected to NanoKVM PCIe MCP.
|
||||
|
||||

|
||||
|
||||
After the connection succeeds, you can send an instruction to OpenCode and let OpenCode view and control the target device through NanoKVM PCIe MCP.
|
||||
|
||||

|
||||
|
||||
To restore the default security behavior, close the current terminal and open a new one. You can also run:
|
||||
|
||||
```bash
|
||||
unset NODE_TLS_REJECT_UNAUTHORIZED
|
||||
```
|
||||
|
||||
### Other AI Tools
|
||||
|
||||
Other MCP-compatible AI tools can also try connecting to NanoKVM PCIe MCP. Support for remote MCP, HTTPS, and tool-call permissions varies between tools and versions.
|
||||
|
||||
If an AI tool cannot handle the certificate used by an HTTPS endpoint, a reverse proxy such as Nginx may be required to handle certificates. This setup is more complex and is not recommended as the first choice for general users.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
After the connection succeeds, you can describe the operation you want to perform in natural language. For example:
|
||||
|
||||
```text
|
||||
Use NanoKVM PCIe to check the current screen and tell me which page the target device is on.
|
||||
```
|
||||
|
||||
```text
|
||||
Use NanoKVM PCIe to click the Settings button on the screen.
|
||||
```
|
||||
|
||||
```text
|
||||
Use NanoKVM PCIe to open a terminal and type ifconfig to check the network information.
|
||||
```
|
||||
|
||||
```text
|
||||
Use NanoKVM PCIe to continue the system installation process based on the current screen.
|
||||
```
|
||||
|
||||
Start with simple and easy-to-confirm operations, such as reading the screen, clicking a clear button, or typing a short command. For high-risk operations such as deleting files, formatting disks, or changing system configuration, confirm the action before allowing the AI tool to proceed.
|
||||
|
||||
## FAQ
|
||||
|
||||
### The AI Tool Cannot Connect to NanoKVM PCIe MCP
|
||||
|
||||
Check:
|
||||
|
||||
+ Whether the NanoKVM PCIe MCP switch is turned on;
|
||||
+ Whether the MCP endpoint is correct;
|
||||
+ Whether the `API Key` is correct;
|
||||
+ Whether the control device and NanoKVM PCIe can reach each other over the network;
|
||||
+ When using an HTTPS endpoint, whether the AI tool can handle the local NanoKVM PCIe certificate;
|
||||
+ Whether a firewall, router, VPN, or security software is blocking the connection;
|
||||
+ Whether NanoKVM PCIe is connected to the network and shows an IP address.
|
||||
|
||||
### The AI Tool Can Connect to MCP, but Cannot Control the Target Device
|
||||
|
||||
Check:
|
||||
|
||||
+ Whether the NanoKVM PCIe web control page can display the target device screen correctly;
|
||||
+ Whether the target device is connected to NanoKVM PCIe correctly;
|
||||
+ Whether the current target device screen requires unlocking, login, or manual confirmation;
|
||||
+ Whether the AI tool allows MCP tool calls;
|
||||
+ Whether keyboard and mouse control works normally in NanoKVM PCIe.
|
||||
|
||||
### The MCP Switch Is Not Shown
|
||||
|
||||
Check:
|
||||
|
||||
+ Whether the NanoKVM PCIe system or application version is too old;
|
||||
+ Whether the current version supports MCP;
|
||||
+ Whether the KVM App needs to be updated from the web control page;
|
||||
+ Whether the settings page has been reopened after the update.
|
||||
|
||||
## Security Notes
|
||||
|
||||
+ MCP gives the AI tool the ability to operate the target device. Connect only trusted AI tools;
|
||||
+ Do not expose the MCP service directly to the public Internet;
|
||||
+ Do not expose the MCP endpoint on untrusted networks;
|
||||
+ Turn off MCP when it is not needed;
|
||||
+ Confirm the AI tool's action before operating important devices;
|
||||
+ Do not leak the NanoKVM PCIe MCP `API Key`;
|
||||
+ When entering passwords, keys, tokens, or other sensitive information, make sure the AI tool and network environment are trusted.
|
||||
@@ -523,6 +523,8 @@ items:
|
||||
file: kvm/NanoKVM/quick_start.md
|
||||
- label: User Guide
|
||||
file: kvm/NanoKVM/user_guide.md
|
||||
- label: MCP
|
||||
file: kvm/NanoKVM/mcp.md
|
||||
- label: Network
|
||||
items:
|
||||
- label: Tailscale
|
||||
@@ -595,6 +597,8 @@ items:
|
||||
file: kvm/NanoKVM_PCIe/quick_start.md
|
||||
- label: User Guide
|
||||
file: kvm/NanoKVM_PCIe/user_guide.md
|
||||
- label: MCP
|
||||
file: kvm/NanoKVM_PCIe/mcp.md
|
||||
- label: Network
|
||||
items:
|
||||
- label: Tailscale
|
||||
|
||||
236
docs/hardware/zh/kvm/NanoKVM/mcp.md
Normal file
@@ -0,0 +1,236 @@
|
||||
---
|
||||
title: MCP 功能
|
||||
keywords: NanoKVM Cube, MCP, AI, Remote Control, KVM, OpenCode
|
||||
update:
|
||||
- date: 2026-08-19
|
||||
version: v0.1
|
||||
author: Liang Ziyue
|
||||
content:
|
||||
- 新增 NanoKVM Cube MCP 功能说明
|
||||
---
|
||||
|
||||
## 简介
|
||||
|
||||
NanoKVM Cube 的 MCP 功能用于将 NanoKVM Cube 接入支持 MCP 的 AI 工具,使 AI 工具可以通过 NanoKVM Cube 查看并控制被控设备。
|
||||
|
||||
连接完成后,AI 工具可以根据被控设备的屏幕内容,辅助执行点击、输入、打开应用、修改设置、排查问题等操作。该功能适合远程运维、系统配置、故障排查和重复性操作辅助等场景。
|
||||
|
||||
> MCP 功能会让 AI 工具具备操作被控设备的能力。使用前请确认 AI 工具来源可信,并避免在不可信网络中开放 MCP 服务。
|
||||
|
||||
## 工作原理
|
||||
|
||||
NanoKVM Cube 开启 MCP 服务后,控制设备上的 AI 工具可以通过页面显示的 `服务地址` 和 `API Key` 连接到 MCP 服务。AI 工具并不直接连接被控设备,而是通过 NanoKVM Cube 间接获取画面并发送控制操作。
|
||||
|
||||
连接关系如下:
|
||||
|
||||
```text
|
||||
AI 工具(控制设备)
|
||||
|
|
||||
| MCP
|
||||
v
|
||||
NanoKVM Cube
|
||||
|
|
||||
| KVM 控制
|
||||
v
|
||||
被控设备
|
||||
```
|
||||
|
||||
其中:
|
||||
|
||||
+ 被控设备通过 HDMI 接口向 NanoKVM Cube 输出画面,并通过 PC USB(HID)接口接收键盘、鼠标等控制操作;
|
||||
+ NanoKVM Cube 负责采集被控设备画面,并向被控设备发送键盘、鼠标等控制操作;
|
||||
+ 控制设备上的 AI 工具通过 MCP 连接 NanoKVM Cube;
|
||||
+ 用户在 AI 工具中发出指令后,AI 工具通过 NanoKVM Cube 辅助控制被控设备。
|
||||
|
||||
## 使用前准备
|
||||
|
||||
使用 MCP 功能前,请先确认:
|
||||
|
||||
+ NanoKVM Cube 已正常连接被控设备;
|
||||
+ NanoKVM Cube 网页控制端可以正常显示被控设备画面;
|
||||
+ NanoKVM Cube 已连接网络,并且已获得 IP 地址;
|
||||
+ 控制设备可以访问 NanoKVM Cube 页面显示的 MCP 服务地址;
|
||||
+ 控制设备上已安装支持 MCP 的 AI 工具,例如 [OpenCode](https://opencode.ai/download) 或其他 MCP Client;
|
||||
+ NanoKVM Cube 的系统和应用版本支持 MCP 功能。
|
||||
|
||||
> 如果页面中没有 MCP 相关选项,请先检查 NanoKVM Cube 系统和应用是否已经更新到支持 MCP 的版本。
|
||||
|
||||
## 开启 MCP 功能
|
||||
|
||||
1. 将 NanoKVM Cube 接入被控设备,并确认被控设备画面可以正常显示。
|
||||
2. 在浏览器地址栏输入 NanoKVM Cube 的 IP 地址,打开 NanoKVM Cube 网页控制端。
|
||||
3. 登录 NanoKVM Cube。
|
||||
4. 进入设置页面。
|
||||
|
||||

|
||||
|
||||
5. 找到 MCP 功能选项。
|
||||
|
||||

|
||||
|
||||
6. 打开 MCP 功能开关。
|
||||
7. 记录页面显示的 `服务地址` 和 `API Key`。
|
||||
|
||||
## 在 AI 工具中添加 MCP
|
||||
|
||||
不同 AI 工具的 MCP 配置方式不同。本节以 OpenCode 为例,演示如何在控制设备上添加 NanoKVM Cube MCP。
|
||||
|
||||
### 获取服务地址和 API Key
|
||||
|
||||
在 NanoKVM Cube 中开启 MCP 功能后,页面会显示 `服务地址` 和 `API Key`。
|
||||
|
||||

|
||||
|
||||
其中:
|
||||
|
||||
+ `服务地址` 是 NanoKVM Cube MCP Server 的完整访问地址,例如 `http://<NanoKVM-IP>/api/mcp` 或 `https://<NanoKVM-IP>/api/mcp`;
|
||||
+ `API Key` 是访问 NanoKVM Cube MCP Server 时使用的认证凭据。
|
||||
|
||||
配置 AI 工具时,请直接复制页面中显示的服务地址,不需要手动拆分 IP、端口或修改协议。
|
||||
|
||||
### OpenCode 添加 MCP
|
||||
|
||||
OpenCode 支持通过全局配置文件添加远程 MCP Server。
|
||||
|
||||
新建或编辑以下配置文件:
|
||||
|
||||
```bash
|
||||
~/.config/opencode/opencode.json
|
||||
```
|
||||
|
||||
配置示例:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"nanokvm": {
|
||||
"type": "remote",
|
||||
"url": "<Endpoint>",
|
||||
"oauth": false,
|
||||
"headers": {
|
||||
"Authorization": "Bearer <API-Key>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
将:
|
||||
|
||||
+ `<Endpoint>` 替换为 NanoKVM Cube MCP 页面显示的 `服务地址`;
|
||||
+ `<API-Key>` 替换为 NanoKVM Cube MCP 页面显示的 `API Key`。
|
||||
|
||||
页面显示的服务地址可能以 HTTP 或 HTTPS 开头,请按页面内容原样填写。建议只在可信局域网中使用 MCP,并优先通过 HTTPS 连接。
|
||||
|
||||
如果服务地址以 HTTPS 开头,且 OpenCode 因 NanoKVM Cube 的本地证书而无法连接,可以在 Linux 环境中设置以下环境变量后启动 OpenCode:
|
||||
|
||||
```bash
|
||||
export NODE_TLS_REJECT_UNAUTHORIZED=0
|
||||
opencode
|
||||
```
|
||||
|
||||
如果使用一条命令启动,也可以写成:
|
||||
|
||||
```bash
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=0 opencode
|
||||
```
|
||||
|
||||
> `NODE_TLS_REJECT_UNAUTHORIZED` 环境变量会关闭当前 OpenCode 进程中的 TLS 证书验证,只建议在可信局域网内连接 NanoKVM Cube MCP 时使用。不要在不可信网络中长期使用该环境变量。
|
||||
|
||||
保存配置后,重新启动 OpenCode。然后查看 MCP Server 是否连接成功:
|
||||
|
||||
```bash
|
||||
opencode mcp list
|
||||
```
|
||||
|
||||
如果使用 HTTPS 服务地址时遇到本地证书验证错误,可以使用:
|
||||
|
||||
```bash
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=0 opencode mcp list
|
||||
```
|
||||
|
||||
如果 `nanokvm` 显示为已连接,说明 OpenCode 已经成功接入 NanoKVM Cube MCP。
|
||||
|
||||

|
||||
|
||||
连接成功后,可以给 OpenCode 发送指令,让 OpenCode 通过 NanoKVM Cube MCP 查看并操作被控设备。
|
||||
|
||||

|
||||
|
||||
如果需要恢复默认安全行为,关闭当前终端窗口后重新打开即可。也可以在当前终端中执行:
|
||||
|
||||
```bash
|
||||
unset NODE_TLS_REJECT_UNAUTHORIZED
|
||||
```
|
||||
|
||||
### 其他 AI 工具
|
||||
|
||||
其他支持 MCP 的 AI 工具也可以尝试连接 NanoKVM Cube MCP。不同工具对远程 MCP、HTTPS 证书和工具调用权限的支持程度不同,请以实际版本为准。
|
||||
|
||||
如果某个 AI 工具无法处理 HTTPS 服务地址所使用的证书,可能需要通过 Nginx 等方式做反向代理并处理证书。但该方案配置步骤较多,不适合作为普通用户的首选使用方式。
|
||||
|
||||
## 使用示例
|
||||
|
||||
连接成功后,可以在 AI 工具中通过自然语言描述希望执行的操作。例如:
|
||||
|
||||
```text
|
||||
使用 NanoKVM Cube,查看当前屏幕内容,并告诉我被控设备停在哪个界面。
|
||||
```
|
||||
|
||||
```text
|
||||
使用 NanoKVM Cube,帮我点击屏幕上的设置按钮。
|
||||
```
|
||||
|
||||
```text
|
||||
使用 NanoKVM Cube,帮我打开终端,并输入 ifconfig 查看网络信息。
|
||||
```
|
||||
|
||||
```text
|
||||
使用 NanoKVM Cube,根据当前屏幕内容,帮我继续完成系统安装流程。
|
||||
```
|
||||
|
||||
建议从简单、可确认的操作开始使用,例如查看屏幕内容、点击明确按钮或输入短命令。涉及删除文件、格式化磁盘、修改系统配置等高风险操作时,请先确认 AI 即将执行的动作。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### AI 工具连接不上 NanoKVM Cube MCP
|
||||
|
||||
请检查:
|
||||
|
||||
+ NanoKVM Cube MCP 开关是否已经打开;
|
||||
+ MCP 服务地址是否填写正确;
|
||||
+ `API Key` 是否填写正确;
|
||||
+ 控制设备和 NanoKVM Cube 是否处于可互相访问的网络中;
|
||||
+ 使用 HTTPS 服务地址时,当前 AI 工具是否支持处理 NanoKVM Cube 的本地证书;
|
||||
+ 防火墙、路由器、VPN 或安全软件是否阻止了连接;
|
||||
+ NanoKVM Cube 是否已经正常联网并显示 IP 地址。
|
||||
|
||||
### AI 工具可以连接 MCP,但无法控制被控设备
|
||||
|
||||
请检查:
|
||||
|
||||
+ NanoKVM Cube 网页控制端是否可以正常显示被控设备画面;
|
||||
+ 被控设备是否已经正确连接 NanoKVM Cube;
|
||||
+ 当前被控设备界面是否需要解锁、登录或人工确认;
|
||||
+ AI 工具是否允许调用 MCP 工具;
|
||||
+ NanoKVM Cube 的键盘、鼠标控制功能是否正常。
|
||||
|
||||
### 页面中找不到 MCP 开关
|
||||
|
||||
请检查:
|
||||
|
||||
+ NanoKVM Cube 系统或应用版本是否过旧;
|
||||
+ 当前版本是否支持 MCP 功能;
|
||||
+ 是否需要先在网页控制端中更新 KVM 应用;
|
||||
+ 更新完成后是否已经重新打开设置页面。
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
+ MCP 功能会让 AI 工具具备操作被控设备的能力,请只连接可信 AI 工具;
|
||||
+ 不要将 MCP 服务直接暴露到公网;
|
||||
+ 不要在不可信网络中开放 MCP 服务地址;
|
||||
+ 使用完成后,如暂时不需要 MCP 功能,建议关闭 MCP 开关;
|
||||
+ 操作重要设备前,请确认 AI 即将执行的动作;
|
||||
+ 不要泄露 NanoKVM Cube MCP 的 `API Key`;
|
||||
+ 输入密码、密钥、令牌等敏感信息时,请确认当前 AI 工具和网络环境可信。
|
||||
236
docs/hardware/zh/kvm/NanoKVM_PCIe/mcp.md
Normal file
@@ -0,0 +1,236 @@
|
||||
---
|
||||
title: MCP 功能
|
||||
keywords: NanoKVM PCIe, MCP, AI, Remote Control, KVM, OpenCode
|
||||
update:
|
||||
- date: 2026-08-19
|
||||
version: v0.1
|
||||
author: Liang Ziyue
|
||||
content:
|
||||
- 新增 NanoKVM PCIe MCP 功能说明
|
||||
---
|
||||
|
||||
## 简介
|
||||
|
||||
NanoKVM PCIe 的 MCP 功能用于将 NanoKVM PCIe 接入支持 MCP 的 AI 工具,使 AI 工具可以通过 NanoKVM PCIe 查看并控制被控设备。
|
||||
|
||||
连接完成后,AI 工具可以根据被控设备的屏幕内容,辅助执行点击、输入、打开应用、修改设置、排查问题等操作。该功能适合远程运维、系统配置、故障排查和重复性操作辅助等场景。
|
||||
|
||||
> MCP 功能会让 AI 工具具备操作被控设备的能力。使用前请确认 AI 工具来源可信,并避免在不可信网络中开放 MCP 服务。
|
||||
|
||||
## 工作原理
|
||||
|
||||
NanoKVM PCIe 开启 MCP 服务后,控制设备上的 AI 工具可以通过页面显示的 `服务地址` 和 `API Key` 连接到 MCP 服务。AI 工具并不直接连接被控设备,而是通过 NanoKVM PCIe 间接获取画面并发送控制操作。
|
||||
|
||||
连接关系如下:
|
||||
|
||||
```text
|
||||
AI 工具(控制设备)
|
||||
|
|
||||
| MCP
|
||||
v
|
||||
NanoKVM PCIe
|
||||
|
|
||||
| KVM 控制
|
||||
v
|
||||
被控设备
|
||||
```
|
||||
|
||||
其中:
|
||||
|
||||
+ 被控设备通过 HDMI 接口向 NanoKVM PCIe 输出画面,并通过 USB HID 接口接收键盘、鼠标等控制操作;USB HID 可以使用 USB-C 线缆或机箱内部 USB 2.0 排针连接;
|
||||
+ NanoKVM PCIe 负责采集被控设备画面,并向被控设备发送键盘、鼠标等控制操作;
|
||||
+ 控制设备上的 AI 工具通过 MCP 连接 NanoKVM PCIe;
|
||||
+ 用户在 AI 工具中发出指令后,AI 工具通过 NanoKVM PCIe 辅助控制被控设备。
|
||||
|
||||
## 使用前准备
|
||||
|
||||
使用 MCP 功能前,请先确认:
|
||||
|
||||
+ NanoKVM PCIe 已正常连接被控设备;
|
||||
+ NanoKVM PCIe 网页控制端可以正常显示被控设备画面;
|
||||
+ NanoKVM PCIe 已连接网络,并且已获得 IP 地址;
|
||||
+ 控制设备可以访问 NanoKVM PCIe 页面显示的 MCP 服务地址;
|
||||
+ 控制设备上已安装支持 MCP 的 AI 工具,例如 [OpenCode](https://opencode.ai/download) 或其他 MCP Client;
|
||||
+ NanoKVM PCIe 的系统和应用版本支持 MCP 功能。
|
||||
|
||||
> 如果页面中没有 MCP 相关选项,请先检查 NanoKVM PCIe 系统和应用是否已经更新到支持 MCP 的版本。
|
||||
|
||||
## 开启 MCP 功能
|
||||
|
||||
1. 将 NanoKVM PCIe 接入被控设备,并确认被控设备画面可以正常显示。
|
||||
2. 在浏览器地址栏输入 NanoKVM PCIe 的 IP 地址,打开 NanoKVM PCIe 网页控制端。
|
||||
3. 登录 NanoKVM PCIe。
|
||||
4. 进入设置页面。
|
||||
|
||||

|
||||
|
||||
5. 找到 MCP 功能选项。
|
||||
|
||||

|
||||
|
||||
6. 打开 MCP 功能开关。
|
||||
7. 记录页面显示的 `服务地址` 和 `API Key`。
|
||||
|
||||
## 在 AI 工具中添加 MCP
|
||||
|
||||
不同 AI 工具的 MCP 配置方式不同。本节以 OpenCode 为例,演示如何在控制设备上添加 NanoKVM PCIe MCP。
|
||||
|
||||
### 获取服务地址和 API Key
|
||||
|
||||
在 NanoKVM PCIe 中开启 MCP 功能后,页面会显示 `服务地址` 和 `API Key`。
|
||||
|
||||

|
||||
|
||||
其中:
|
||||
|
||||
+ `服务地址` 是 NanoKVM PCIe MCP Server 的完整访问地址,例如 `http://<NanoKVM-IP>/api/mcp` 或 `https://<NanoKVM-IP>/api/mcp`;
|
||||
+ `API Key` 是访问 NanoKVM PCIe MCP Server 时使用的认证凭据。
|
||||
|
||||
配置 AI 工具时,请直接复制页面中显示的服务地址,不需要手动拆分 IP、端口或修改协议。
|
||||
|
||||
### OpenCode 添加 MCP
|
||||
|
||||
OpenCode 支持通过全局配置文件添加远程 MCP Server。
|
||||
|
||||
新建或编辑以下配置文件:
|
||||
|
||||
```bash
|
||||
~/.config/opencode/opencode.json
|
||||
```
|
||||
|
||||
配置示例:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"nanokvm": {
|
||||
"type": "remote",
|
||||
"url": "<Endpoint>",
|
||||
"oauth": false,
|
||||
"headers": {
|
||||
"Authorization": "Bearer <API-Key>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
将:
|
||||
|
||||
+ `<Endpoint>` 替换为 NanoKVM PCIe MCP 页面显示的 `服务地址`;
|
||||
+ `<API-Key>` 替换为 NanoKVM PCIe MCP 页面显示的 `API Key`。
|
||||
|
||||
页面显示的服务地址可能以 HTTP 或 HTTPS 开头,请按页面内容原样填写。建议只在可信局域网中使用 MCP,并优先通过 HTTPS 连接。
|
||||
|
||||
如果服务地址以 HTTPS 开头,且 OpenCode 因 NanoKVM PCIe 的本地证书而无法连接,可以在 Linux 环境中设置以下环境变量后启动 OpenCode:
|
||||
|
||||
```bash
|
||||
export NODE_TLS_REJECT_UNAUTHORIZED=0
|
||||
opencode
|
||||
```
|
||||
|
||||
如果使用一条命令启动,也可以写成:
|
||||
|
||||
```bash
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=0 opencode
|
||||
```
|
||||
|
||||
> `NODE_TLS_REJECT_UNAUTHORIZED` 环境变量会关闭当前 OpenCode 进程中的 TLS 证书验证,只建议在可信局域网内连接 NanoKVM PCIe MCP 时使用。不要在不可信网络中长期使用该环境变量。
|
||||
|
||||
保存配置后,重新启动 OpenCode。然后查看 MCP Server 是否连接成功:
|
||||
|
||||
```bash
|
||||
opencode mcp list
|
||||
```
|
||||
|
||||
如果使用 HTTPS 服务地址时遇到本地证书验证错误,可以使用:
|
||||
|
||||
```bash
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=0 opencode mcp list
|
||||
```
|
||||
|
||||
如果 `nanokvm` 显示为已连接,说明 OpenCode 已经成功接入 NanoKVM PCIe MCP。
|
||||
|
||||

|
||||
|
||||
连接成功后,可以给 OpenCode 发送指令,让 OpenCode 通过 NanoKVM PCIe MCP 查看并操作被控设备。
|
||||
|
||||

|
||||
|
||||
如果需要恢复默认安全行为,关闭当前终端窗口后重新打开即可。也可以在当前终端中执行:
|
||||
|
||||
```bash
|
||||
unset NODE_TLS_REJECT_UNAUTHORIZED
|
||||
```
|
||||
|
||||
### 其他 AI 工具
|
||||
|
||||
其他支持 MCP 的 AI 工具也可以尝试连接 NanoKVM PCIe MCP。不同工具对远程 MCP、HTTPS 证书和工具调用权限的支持程度不同,请以实际版本为准。
|
||||
|
||||
如果某个 AI 工具无法处理 HTTPS 服务地址所使用的证书,可能需要通过 Nginx 等方式做反向代理并处理证书。但该方案配置步骤较多,不适合作为普通用户的首选使用方式。
|
||||
|
||||
## 使用示例
|
||||
|
||||
连接成功后,可以在 AI 工具中通过自然语言描述希望执行的操作。例如:
|
||||
|
||||
```text
|
||||
使用 NanoKVM PCIe,查看当前屏幕内容,并告诉我被控设备停在哪个界面。
|
||||
```
|
||||
|
||||
```text
|
||||
使用 NanoKVM PCIe,帮我点击屏幕上的设置按钮。
|
||||
```
|
||||
|
||||
```text
|
||||
使用 NanoKVM PCIe,帮我打开终端,并输入 ifconfig 查看网络信息。
|
||||
```
|
||||
|
||||
```text
|
||||
使用 NanoKVM PCIe,根据当前屏幕内容,帮我继续完成系统安装流程。
|
||||
```
|
||||
|
||||
建议从简单、可确认的操作开始使用,例如查看屏幕内容、点击明确按钮或输入短命令。涉及删除文件、格式化磁盘、修改系统配置等高风险操作时,请先确认 AI 即将执行的动作。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### AI 工具连接不上 NanoKVM PCIe MCP
|
||||
|
||||
请检查:
|
||||
|
||||
+ NanoKVM PCIe MCP 开关是否已经打开;
|
||||
+ MCP 服务地址是否填写正确;
|
||||
+ `API Key` 是否填写正确;
|
||||
+ 控制设备和 NanoKVM PCIe 是否处于可互相访问的网络中;
|
||||
+ 使用 HTTPS 服务地址时,当前 AI 工具是否支持处理 NanoKVM PCIe 的本地证书;
|
||||
+ 防火墙、路由器、VPN 或安全软件是否阻止了连接;
|
||||
+ NanoKVM PCIe 是否已经正常联网并显示 IP 地址。
|
||||
|
||||
### AI 工具可以连接 MCP,但无法控制被控设备
|
||||
|
||||
请检查:
|
||||
|
||||
+ NanoKVM PCIe 网页控制端是否可以正常显示被控设备画面;
|
||||
+ 被控设备是否已经正确连接 NanoKVM PCIe;
|
||||
+ 当前被控设备界面是否需要解锁、登录或人工确认;
|
||||
+ AI 工具是否允许调用 MCP 工具;
|
||||
+ NanoKVM PCIe 的键盘、鼠标控制功能是否正常。
|
||||
|
||||
### 页面中找不到 MCP 开关
|
||||
|
||||
请检查:
|
||||
|
||||
+ NanoKVM PCIe 系统或应用版本是否过旧;
|
||||
+ 当前版本是否支持 MCP 功能;
|
||||
+ 是否需要先在网页控制端中更新 KVM 应用;
|
||||
+ 更新完成后是否已经重新打开设置页面。
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
+ MCP 功能会让 AI 工具具备操作被控设备的能力,请只连接可信 AI 工具;
|
||||
+ 不要将 MCP 服务直接暴露到公网;
|
||||
+ 不要在不可信网络中开放 MCP 服务地址;
|
||||
+ 使用完成后,如暂时不需要 MCP 功能,建议关闭 MCP 开关;
|
||||
+ 操作重要设备前,请确认 AI 即将执行的动作;
|
||||
+ 不要泄露 NanoKVM PCIe MCP 的 `API Key`;
|
||||
+ 输入密码、密钥、令牌等敏感信息时,请确认当前 AI 工具和网络环境可信。
|
||||
@@ -522,6 +522,8 @@ items:
|
||||
file: kvm/NanoKVM/quick_start.md
|
||||
- label: 用户指南
|
||||
file: kvm/NanoKVM/user_guide.md
|
||||
- label: MCP 功能
|
||||
file: kvm/NanoKVM/mcp.md
|
||||
- label: 二次开发
|
||||
file: kvm/NanoKVM/development.md
|
||||
- label: 网络
|
||||
@@ -596,6 +598,8 @@ items:
|
||||
file: kvm/NanoKVM_PCIe/quick_start.md
|
||||
- label: 用户指南
|
||||
file: kvm/NanoKVM_PCIe/user_guide.md
|
||||
- label: MCP 功能
|
||||
file: kvm/NanoKVM_PCIe/mcp.md
|
||||
- label: 二次开发
|
||||
file: kvm/NanoKVM/development.md
|
||||
- label: 网络
|
||||
|
||||