Skip to main content
Glama

PiKVM MCP Server

SonarQube Cloud

MCP Badge

Give AI agents hands. This MCP server connects Claude Code (or any MCP client) directly to a PiKVM device, giving AI full keyboard, mouse, and screen access to a physical machine -- no browser automation, no virtual desktops, no emulators.

Point it at real hardware. Let the AI see the screen, type commands, click buttons, and navigate GUIs on a machine it could never otherwise touch.

Automatic Mouse Calibration

IP-KVM devices translate mouse coordinates through multiple layers — USB HID emulation, host-side input drivers, display scaling — each introducing positional error. Existing KVM products either ignore this (requiring manual correction) or offer limited auto-sync that only detects cursor acceleration in a fixed corner region.

This MCP server takes a different approach. The pikvm_auto_calibrate tool uses a vision-based algorithm that:

  1. Moves the cursor a known distance across multiple randomized screen positions

  2. Diffs screenshot pairs to isolate the cursor via connected-component analysis

  3. Computes correction factors from detected vs commanded movement using median aggregation

  4. Self-verifies by moving to target positions and confirming the cursor lands within 20px

The entire process runs in ~30-60 seconds with no human intervention. Noisy screens (tooltips, animations, dynamic content) are handled through multi-round sampling, ratio divergence filtering, and outlier-resistant statistics — the algorithm discards bad data and still converges on accurate factors.

This is the first IP-KVM tooling — commercial or open source — to implement fully automated mouse coordinate calibration via computer vision. It is what makes precise AI-driven mouse control over a network KVM practical.

See it in action

The video below shows Claude Code using this MCP server to autonomously interact with a Raspberry Pi desktop: taking a screenshot to identify the OS, opening a text editor from the menu, typing text, and closing the application -- all through the PiKVM hardware interface.

Demo Video

This next demonstration shows Claude, connected via the PiKVM MCP server, responding to a natural language prompt to auto-calibrate its mouse coordinate scaling before performing a series of precision mouse tasks on a remote machine. The session concludes with Claude autonomously drawing a house in MS Paint — a simple but effective showcase of accurate, AI-driven input control over an isolated system.

Demo Video

Features

  • Automatic mouse calibration — Vision-based cursor detection computes coordinate correction factors with no manual measurement. The first fully automated calibration for IP-KVM.

  • Screenshot capture — Get current screen as JPEG image

  • Text typing — Type text with proper special character handling via keymaps

  • Keyboard control — Send individual keys or key combinations (e.g., Ctrl+Alt+Delete)

  • Mouse control — Move, click, and scroll with calibrated coordinate correction

Related MCP server: qemu-mcp-server

Installation

npm install
npm run build

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Edit .env:

PIKVM_HOST=https://<your-pikvm-ip>
PIKVM_USERNAME=admin
PIKVM_PASSWORD=your_password
PIKVM_VERIFY_SSL=false
PIKVM_DEFAULT_KEYMAP=en-us

Usage with Claude Code

Requires Node.js 18+. This server uses ES modules. If node --version shows an older version, replace "command": "node" with the full path to a compatible binary (e.g. "/usr/local/bin/node" or your nvm path like "~/.nvm/versions/node/v22.x.x/bin/node"). This is common when nvm's default alias points to an older version.

Add to your Claude Code MCP settings (~/.config/claude-code/settings.json or via the settings UI):

{
  "mcpServers": {
    "pikvm": {
      "command": "node",
      "args": ["/path/to/pikvm_mcp_server/dist/index.js"],
      "env": {
        "PIKVM_HOST": "https://<your-pikvm-ip>",
        "PIKVM_USERNAME": "admin",
        "PIKVM_PASSWORD": "your_password"
      }
    }
  }
}

Or if using the .env file:

{
  "mcpServers": {
    "pikvm": {
      "command": "node",
      "args": ["/path/to/pikvm_mcp_server/dist/index.js"]
    }
  }
}

Available Tools

Display

  • pikvm_screenshot - Capture current screen as JPEG (optional: maxWidth, maxHeight, quality)

  • pikvm_get_resolution - Get screen resolution and valid coordinate ranges

Keyboard

  • pikvm_type - Type text with keymap-aware special character handling (required: text; optional: keymap, slow, delay)

  • pikvm_key - Send a key or key combo, e.g. Ctrl+Alt+Del (required: key; optional: modifiers, state)

  • pikvm_shortcut - Send multiple keys pressed simultaneously (required: keys array)

Mouse

  • pikvm_mouse_move - Move cursor to absolute pixel position or relative delta (required: x, y; optional: relative)

  • pikvm_mouse_click - Click a mouse button, optionally at a position (optional: button, x, y, state)

  • pikvm_mouse_scroll - Scroll the mouse wheel (required: deltaY; optional: deltaX)

Calibration

  • pikvm_auto_calibrate - Automatically detect cursor and compute calibration factors (preferred)

  • pikvm_calibrate - Start manual calibration by moving cursor to screen center for visual verification

  • pikvm_set_calibration - Apply correction factors calculated from calibration (required: factorX, factorY)

  • pikvm_get_calibration - Get current calibration state

  • pikvm_clear_calibration - Reset to uncalibrated mode

Skills (Prompts & Skill Tools)

The server exposes 15 skills that provide structured guidance for agents. Each skill is available via two discovery paths:

  • MCP Prompts — prompts/list / prompts/get for clients that support the Prompts capability.

  • Skill Tools — tools/list / tools/call as skill_* read-only tools, ensuring visibility in marketplaces (e.g. LobeHub) that index tools only.

Tool Guides

Prompt Name

Skill Tool

Description

take-screenshot

skill_take_screenshot

Capturing screenshots with pikvm_screenshot

check-resolution

skill_check_resolution

Checking screen resolution with pikvm_get_resolution

type-text

skill_type_text

Typing text with pikvm_type

send-key

skill_send_key

Sending keys with pikvm_key

send-shortcut

skill_send_shortcut

Sending keyboard shortcuts with pikvm_shortcut

move-mouse

skill_move_mouse

Moving the mouse with pikvm_mouse_move

click-element

skill_click_element

Clicking with pikvm_mouse_click

scroll-page

skill_scroll_page

Scrolling with pikvm_mouse_scroll

auto-calibrate

skill_auto_calibrate

Automatic mouse calibration with pikvm_auto_calibrate

Workflow Recipes

Prompt Name

Skill Tool

Arguments

Description

setup-session-workflow

skill_setup_session_workflow

—

Initialize a PiKVM session

calibrate-mouse-workflow

skill_calibrate_mouse_workflow

—

Calibrate mouse coordinates

click-ui-element-workflow

skill_click_ui_element_workflow

element_description (required)

Find and click a UI element

fill-form-workflow

skill_fill_form_workflow

form_description (optional)

Fill in a form on screen

navigate-desktop-workflow

skill_navigate_desktop_workflow

goal (required)

Navigate a desktop environment

auto-calibrate-mouse-workflow

skill_auto_calibrate_mouse_workflow

—

Automatic mouse calibration

See docs/skills/ for detailed human-readable guides.

Key Codes Reference

Common key codes for pikvm_key and pikvm_shortcut:

  • Letters: KeyA, KeyB, ... KeyZ

  • Numbers: Digit0, Digit1, ... Digit9

  • Function keys: F1, F2, ... F12

  • Modifiers: ShiftLeft, ShiftRight, ControlLeft, ControlRight, AltLeft, AltRight, MetaLeft, MetaRight

  • Special: Enter, Escape, Backspace, Tab, Space, Delete, Insert, Home, End, PageUp, PageDown

  • Arrows: ArrowUp, ArrowDown, ArrowLeft, ArrowRight

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening a PR. It covers the build commands, the PR workflow and DCO sign-off (git commit -s). Please follow the Code of Conduct.

To report a security vulnerability, don't open a public issue. Follow SECURITY.md instead.

License

GPL-3.0 - See LICENSE for details.

Available Tools

28 tools
pikvm_auto_calibrateA

Automatically calibrate mouse coordinates by detecting the cursor position via screenshot diffing. This is more accurate than manual calibration. Moves the mouse multiple times, compares screenshots to find the cursor, and computes calibration factors. Other tools are blocked during calibration.

Inputs: rounds, verifyRounds, moveDelayMs, mergeRadius, +3 more.

pikvm_calibrateA

Start mouse coordinate calibration. Moves cursor to screen center and returns expected position. Take a screenshot after calling this to visually verify actual cursor position, then call pikvm_set_calibration with calculated factors.

Inputs: no named parameters.

pikvm_clear_calibrationA

Clear mouse calibration, reverting to uncalibrated mode.

Inputs: no named parameters.

pikvm_get_calibrationA

Get current mouse calibration state. Returns null if not calibrated.

Inputs: no named parameters.

pikvm_get_resolutionA

Get the current screen resolution of the remote machine. Useful for knowing valid coordinate ranges for mouse operations.

Inputs: no named parameters.

pikvm_keyB

Send a key or key combination to the remote machine. Use JavaScript key codes (e.g., KeyA, Enter, ControlLeft).

Inputs: key (required), modifiers, state.

pikvm_mouse_clickB

Click a mouse button on the remote machine. Optionally move to a pixel position first.

Inputs: button, x, y, state.

pikvm_mouse_moveA

Move the mouse cursor to a position on the remote machine. For absolute moves, coordinates are in screen pixels (0,0 = top-left). For relative moves, deltas are clamped to -127 to 127.

Inputs: x (required), y (required), relative.

pikvm_mouse_scrollC

Scroll the mouse wheel on the remote machine.

Inputs: deltaY (required), deltaX.

pikvm_screenshotA

Capture a screenshot from the PiKVM video stream. Returns the current screen as a JPEG image.

Inputs: maxWidth, maxHeight, quality.

pikvm_set_calibrationA

Set mouse coordinate calibration factors. Calculate factors as: factorX = expected_x / actual_x, factorY = expected_y / actual_y. For example, if calibration moved cursor to expected (960, 540) but it landed at (720, 405), factors would be 960/720=1.33 and 540/405=1.33.

Inputs: factorX (required), factorY (required).

pikvm_shortcutA

Send a keyboard shortcut (multiple keys pressed simultaneously). Example: Ctrl+Alt+Delete

Inputs: keys (required).

pikvm_typeA

Type text on the remote machine using PiKVM. Handles special characters correctly via keymap conversion.

Inputs: text (required), keymap, slow, delay.

skill_auto_calibrateC
Read-onlyIdempotent

Guide for automatic mouse calibration with pikvm_auto_calibrate

Inputs: no named parameters.

skill_auto_calibrate_mouse_workflowC
Read-onlyIdempotent

Step-by-step procedure for automatic mouse calibration

Inputs: no named parameters.

skill_calibrate_mouse_workflowA
Read-onlyIdempotent

Step-by-step procedure for calibrating mouse coordinates

Inputs: no named parameters.

skill_check_resolutionC
Read-onlyIdempotent

Guide for checking screen resolution with pikvm_get_resolution

Inputs: no named parameters.

skill_click_elementC
Read-onlyIdempotent

Guide for clicking with pikvm_mouse_click

Inputs: no named parameters.

skill_click_ui_element_workflowB
Read-onlyIdempotent

Step-by-step procedure for finding and clicking a UI element

Inputs: element_description (required).

skill_fill_form_workflowC
Read-onlyIdempotent

Step-by-step procedure for filling in a form on screen

Inputs: form_description.

skill_move_mouseC
Read-onlyIdempotent

Guide for moving the mouse with pikvm_mouse_move

Inputs: no named parameters.

skill_navigate_desktop_workflowC
Read-onlyIdempotent

Step-by-step procedure for navigating a desktop environment

Inputs: goal (required).

skill_scroll_pageC
Read-onlyIdempotent

Guide for scrolling with pikvm_mouse_scroll

Inputs: no named parameters.

skill_send_keyD
Read-onlyIdempotent

Guide for sending keys with pikvm_key

Inputs: no named parameters.

skill_send_shortcutD
Read-onlyIdempotent

Guide for sending keyboard shortcuts with pikvm_shortcut

Inputs: no named parameters.

skill_setup_session_workflowB
Read-onlyIdempotent

Step-by-step procedure for initializing a PiKVM session

Inputs: no named parameters.

skill_take_screenshotC
Read-onlyIdempotent

Guide for capturing screenshots with pikvm_screenshot

Inputs: no named parameters.

skill_type_textC
Read-onlyIdempotent

Guide for typing text with pikvm_type

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 28 tools

    Disambiguation2/5

    Many skill_ tools directly duplicate the functionality of pikvm_ tools (e.g., skill_auto_calibrate vs pikvm_auto_calibrate), causing ambiguity. Also, skill tools like 'skill_click_element' and 'skill_click_ui_element_workflow' overlap, making it hard to distinguish between documentation and actual actions.

    Naming Consistency3/5

    Two distinct naming prefixes exist: pikvm_ (consistent verb_noun) and skill_ (inconsistent mix of 'guide', 'workflow', and action descriptions). While each prefix is internally consistent, the mix creates confusion and breaks a unified pattern.

    Tool Count3/5

    28 tools is somewhat high for the domain. The actual action tools are about 12, and the remaining 16 are skill guides that could be consolidated into tool descriptions or fewer workflow tools. The count feels inflated.

    Completeness3/5

    Core actions for remote mouse, keyboard, screenshots, and calibration are covered. However, missing essential PiKVM features like power control, video settings, or media mounting leave some gaps. The skill tools provide workflow guidance but don't add functional breadth.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives AI agents human-like control over Windows via visual perception and simulated mouse and keyboard input, enabling automation of any application without APIs.
      33 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that enables AI to see and control a physical computer via a JetKVM device for screen viewing, mouse/keyboard input, media mounting, and power management.
      25
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that gives AI agents smart hands for physical machines, controlling them via IP-KVM, BMC, and SSH with visual boot-phase classification and operator-gated actions.
      34
      118 PyPI
      19
      Apache 2.0