ovh-ikvm

This MCP server exposes OVH iKVM/IPMI consoles for bare metal servers as MCP tools that you can call from an LLM or AI agent. The server provides two primary tools: list_servers and get_screenshot. list_servers queries the OVH API to enumerate all configured bare metal servers that support iKVM/IPMI access, returning a JSON array of server objects with identifiers and metadata. get_screenshot connects to the server's iKVM/IPMI console, captures a frame from the KVM stream, and returns a PNG image optimized for AI vision (with options to request the raw image by setting raw=true). The server handles authentication with OVH, establishes a viewer session, and streams a JPEG frame over WebSocket, which is then converted to a PNG image for the requester. To use these tools, start the server, ensure the required OVH credentials are configured, and then call list_servers to discover targets before requesting screenshots for specific servers. The MCP transport uses HTTP and can be integrated with Claude, Cursor, Windsurf, or other compatible agents by pointing the agent’s MCP config to the server’s /mcp endpoint.

Typical workflow:

• Start the MCP server and ensure OVH credentials are available in the environment.
• Call list_servers to enumerate available servers.
• Choose a serverId from the list and call get_screenshot with that serverId to retrieve a PNG image of the console.
• If needed, pass raw=true to get the unprocessed image for custom post-processing.

Examples of how the tools respond:

• list_servers returns a JSON array of server objects with id, name, provider, datacenter, and IP.
• get_screenshot returns a base64-encoded PNG image block representing the server console screenshot.

Prerequisites:

• Git
• Node.js or Bun environment (this project uses Bun, but the server is accessible via a Node.js entry point as configured)
• OVH API credentials (Application Key, Application Secret, Consumer Key)
• Optional: Docker if you prefer containerized usage

Installation steps:

1. Clone the repository

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

2. Install dependencies (Bun is recommended in the project setup)

bun install

3. Set required OVH credentials in your environment (see below for details)
4. Start the MCP server (example using Bun)

bun start

Optional Docker usage:

• Run the pre-built image with the necessary environment variables and port mapping:

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

Configuration notes:

• The MCP server expects OVH credentials as environment variables: OVH_ENDPOINT, OVH_APPLICATION_KEY, OVH_APPLICATION_SECRET, OVH_CONSUMER_KEY.
• By default, the server runs on http://localhost:3001/mcp. Adjust port mappings as needed when using Docker or reverse proxies.

Tips and common issues:

• Ensure OVH credentials have the necessary permissions for iKVM access and session management (GET /dedicated/server, /dedicated/server/*, and related endpoints).
• The server uses a health check endpoint at /health when running in Docker; use it to monitor container health.
• If you encounter authentication errors, re-issue and re-authorize the consumer key in OVH and verify that all three credentials are correctly exported in the environment.
• When embedding in AI agents, ensure the agent’s MCP config points to http://localhost:3001/mcp (or the deployed host/port) and that the agent’s environment mirrors the OVH credentials for the running process.
• The image capture workflow relies on the OVH iKVM HTML5 viewer; if the viewer requires a login or has session expiration, ensure the session creation logic handles refresh if needed.
• If you deploy via Docker, consider adding a restart policy and a health check script to automatically recover from transient OVH API outages or WebSocket disconnects.