Ovh Ikvm MCP

ovh-ikvm-mcp

 ](https://github.com/xd-ventures/ovh-ikvm-mcp/actions/workflows/docker.yml) 

MCP服务器，使LLM能够通过iKVM/IPMI直观地访问裸机服务器控制台。捕获远程服务器屏幕的屏幕截图，以便对裸机部署进行人工智能调试。

概述

此MCP（模型上下文协议）服务器将裸机服务器iKVM控制台作为LLM可以使用的工具公开。LLM可以列出可用的服务器并请求其控制台输出的屏幕截图，这对于调试启动问题、内核死机、网络配置错误以及服务器屏幕上可见的其他问题非常有用。

运作原理

LLM ──MCP──► ikvm-mcp server ──OVH API──► get viewer URL
                    │
                    ├──KVM WebSocket──► extract JPEG frame ──► PNG screenshot (AMI/ASRockRack BMC)
                    └──VNC/RFB over WebSocket──► capture framebuffer ──► PNG screenshot (standard VNC)

1. MCP服务器通过云提供商API（OVH）进行身份验证
2. 请求iKVM/IPMI HTML5控制台会话
3. 建立BMC会话（从查看器页面提取会话cookie和CSRF令牌）
4. 连接到KVM WebSocket，接收JPEG视频帧
5. 提取第一个完整的JPEG帧并将其转换为PNG
6. 通过MCP将图像返回给LLM

支持的提供商

MCP工具

list_servers

列出所有具有iKVM/IPMI访问权限的可用裸机服务器。

参数： 无

退货： 服务器对象的JSON数组：

[
  {
    "id": "ns1234567.ip-1-2-3.eu",
    "name": "ns1234567.ip-1-2-3.eu",
    "provider": "ovh",
    "datacenter": "sbg3",
    "ip": "1.2.3.4"
  }
]

get_screenshot

捕获服务器iKVM/IPMI控制台屏幕的屏幕截图。返回针对LLM视觉优化的PNG图像（2倍高档+亮度提升）。集 raw=true 以获得原始的未处理图像。

参数：

退货： PNG图像内容块（base64编码）

设置

先决条件

• 包子 >= 1.0
• OVH API凭证（应用程序密钥、应用程序机密、消费者密钥）

OVH API证书

1. 在以下位置创建应用程序https://eu.api.ovh.com/createApp/（或您所在地区的同等机构： ca.api.ovh.com, api.us.ovhcloud.com)
2. 注意 程序键 和 应用程序密钥
3. 请求具有所需权限的消费者密钥：

curl -X POST https://eu.api.ovh.com/1.0/auth/credential \
  -H "X-Ovh-Application: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accessRules": [
      { "method": "GET", "path": "/dedicated/server" },
      { "method": "GET", "path": "/dedicated/server/*" },
      { "method": "POST", "path": "/dedicated/server/*/features/ipmi/access" },
      { "method": "GET", "path": "/dedicated/server/*/features/ipmi/access" },
      { "method": "GET", "path": "/dedicated/server/*/task/*" }
    ]
  }'

1. 该回复包括 consumerKey 和一个 validationUrl --在浏览器中打开URL以授权密钥

安装

git clone https://github.com/xd-ventures/ovh-ikvm-mcp.git
cd ovh-ikvm-mcp
bun install

配置

设置所需的环境变量：

export OVH_ENDPOINT="eu"                    # API region: eu, ca, or us
export OVH_APPLICATION_KEY="your-app-key"
export OVH_APPLICATION_SECRET="your-app-secret"
export OVH_CONSUMER_KEY="your-consumer-key"

跑步

bun start

服务器启动于 http://localhost:3001/mcp 默认情况下。

码头工人

每次推送时，预构建的映像都会发布到GitHub容器注册表 main.

docker run --rm \
  -e OVH_ENDPOINT=eu \
  -e OVH_APPLICATION_KEY=your-app-key \
  -e OVH_APPLICATION_SECRET=your-app-secret \
  -e OVH_CONSUMER_KEY=your-consumer-key \
  -p 3001:3001 \
  ghcr.io/xd-ventures/ovh-ikvm-mcp:latest

容器以非root用户身份运行，并包括对以下内容的健康检查 /health.

您还可以在本地构建映像：

docker build -t ovh-ikvm-mcp .
docker run --rm -e OVH_ENDPOINT=eu -e OVH_APPLICATION_KEY=... -e OVH_APPLICATION_SECRET=... -e OVH_CONSUMER_KEY=... -p 3001:3001 ovh-ikvm-mcp

与AI编码代理一起使用

服务器使用 可流式传输的HTTP 传输（不是stdio），因此所有代理都通过HTTP连接到它。首先启动服务器，然后配置您的代理以指向它。

1.启动服务器：

cd ovh-ikvm-mcp
export OVH_ENDPOINT="eu"
export OVH_APPLICATION_KEY="your-app-key"
export OVH_APPLICATION_SECRET="your-app-secret"
export OVH_CONSUMER_KEY="your-consumer-key"
bun start

您应该看到： ikvm-mcp server listening on http://localhost:3001/mcp

2.配置您的代理 （选一个）：

______________________________________________________________________

克劳德代码

通过CLI注册：

claude mcp add ikvm --transport http http://localhost:3001/mcp

或添加到您的项目 .mcp.json 所以队友们会自动得到它：

{
  "mcpServers": {
    "ikvm": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

验证它是否已连接：

claude mcp list

确保在运行的终端中设置了OVH环境变量 bun start.

______________________________________________________________________

克劳德桌面版

添加到您的Claude Desktop MCP配置中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ikvm": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

保存后，重新启动Claude Desktop。输入框中的锤子图标确认MCP工具已加载。

______________________________________________________________________

光标

添加 .cursor/mcp.json 在项目根目录中（或 ~/.cursor/mcp.json 全球）：

{
  "mcpServers": {
    "ikvm": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

保存后，打开光标设置>MCP并验证 ikvm 服务器显示绿色指示器。

______________________________________________________________________

帆板运动

添加 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ikvm": {
      "serverUrl": "http://localhost:3001/mcp"
    }
  }
}

______________________________________________________________________

示例提示

连接后，您可以对任何代理使用这些提示：

列出服务器并截图：

List my bare metal servers using the ikvm MCP, then take a screenshot
of the first server's console. Describe what you see on the screen.

调试无法启动的服务器：

My server ns1234567.ip-1-2-3.eu is stuck during boot. Take a screenshot
of its console and diagnose the issue. If you see a kernel panic or
GRUB error, suggest how to fix it.

监视服务器状态：

Take a screenshot of ns1234567.ip-1-2-3.eu console. Is the server
at a login prompt, showing an error, or still booting? If it's at
a login prompt, the OS reinstall was successful.

比较原始输出与优化输出：

Take two screenshots of ns1234567.ip-1-2-3.eu — one default (optimized)
and one with raw=true. Compare the readability.

发展

# Install dependencies
bun install

# Run tests
bun test

# Run with watch mode
bun run dev

# Type check
bun run typecheck

# Lint
bun run lint

# Lint and auto-fix
bun run lint:fix

# Format
bun run format

测试

测试使用Bun的内置测试运行器：

• 模拟BMC服务器 --使用会话认证和JPEG帧WebSocket模拟ASRockRack/AMI BMC
• 测试VNC服务器 --为VNC客户端测试提供已知映像的最小RFB服务器
• 模拟OVH API -使用身份验证模拟OVH REST API端点
• 内存中的MCP传输 --测试无HTTP开销的MCP工具调用

运行完整的验证套件：

bun run typecheck && bun run lint && bun test

建筑

src/
├── index.ts              # Entry point — Bun HTTP server with MCP transport
├── kvm/
│   ├── types.ts          # KVM/BMC session types
│   ├── bmc-session.ts    # BMC session establishment (cookie + CSRF extraction)
│   ├── screenshot.ts     # KVM screenshot: IVTP WebSocket → AST2500 decode → PNG
│   ├── optimize.ts       # LLM vision optimization (2x upscale + brightness boost)
│   └── decoder-fetcher.ts # Runtime fetcher for AST2500 decoder from BMC
├── vnc/
│   ├── rfb-client.ts     # VNC/RFB protocol client over WebSocket
│   ├── encodings.ts      # RFB framebuffer encoding decoders (Raw, CopyRect)
│   ├── types.ts          # RFB protocol types and constants
│   └── screenshot.ts     # High-level: connect → capture → PNG encode
├── providers/
│   ├── types.ts          # Provider interface (listServers, getScreenshot)
│   └── ovh/
│       ├── api.ts        # OVH API client with request signing
│       ├── provider.ts   # OVH provider implementation
│       └── types.ts      # OVH-specific types
└── mcp/
    └── server.ts         # MCP server setup + tool definitions

提供者接口

添加新的提供者意味着实现 Provider 接口：

interface Provider {
  name: string;
  listServers(): Promise;
  getScreenshot(serverId: string): Promise;
}

AMI KVM客户端

OVH服务器使用ASRockRack/AMI BMC固件，该固件具有专有的WebSocket KVM协议，位于 wss:///kvmKVM客户端：

1. 获取查看器重定向页面并提取 QSESSIONID 饼干和 garc CSRF令牌
2. 连接到KVM WebSocket端点
3. 扫描传入的二进制消息中的JPEG SOI(0xFFD8)/EOI(0xFFD9)标记
4. 提取第一个完整的JPEG帧并将其转换为PNG

VNC/RFB客户端

VNC客户端直接连接到使用标准VNC的iKVM查看器公开的WebSocket端点，执行RFB协议握手（版本协商、安全、帧缓冲区请求），而不需要无头浏览器。

支持的RFB功能：

• 协议版本：3.3、3.7、3.8
• 安全性：无，VNC身份验证（DES质询响应）
• 编码：原始、CopyRect

致谢

此项目通过以下方式连接到BMC固件 美国大趋势股份有限公司（AMI）. AST2500视频解码器在运行时从BMC的web界面获取 并且不与此项目一起分发。看 通知 了解详情。

贡献

看 贡献.md 用于开发设置、工作流程和指南。

该项目遵循 贡献者契约3.0 行为准则。

要报告安全漏洞，请参阅 安全.md.

许可证

Apache 2.0——请参阅 许可证.