PiKVM MCP Server
Controls a real PiKVM-connected machine, giving AI keyboard, mouse, and screen access over the network.
Capture JPEG screenshots and get screen resolution/coordinate ranges.
Type text with keymap handling, send individual keys/combos, and keyboard shortcuts.
Move, click, and scroll the mouse using absolute or relative coordinates.
Automatically calibrate mouse coordinates via screenshot diffing, or manage manual calibration.
Use built-in skill guides/workflows for screenshots, typing, clicking UI elements, filling forms, desktop navigation, and calibration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PiKVM MCP Server take a screenshot of the desktop"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PiKVM MCP Server
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:
Moves the cursor a known distance across multiple randomized screen positions
Diffs screenshot pairs to isolate the cursor via connected-component analysis
Computes correction factors from detected vs commanded movement using median aggregation
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.

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.

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 buildConfiguration
Copy .env.example to .env and configure:
cp .env.example .envEdit .env:
PIKVM_HOST=https://<your-pikvm-ip>
PIKVM_USERNAME=admin
PIKVM_PASSWORD=your_password
PIKVM_VERIFY_SSL=false
PIKVM_DEFAULT_KEYMAP=en-usUsage with Claude Code
Requires Node.js 18+. This server uses ES modules. If
node --versionshows 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 verificationpikvm_set_calibration- Apply correction factors calculated from calibration (required: factorX, factorY)pikvm_get_calibration- Get current calibration statepikvm_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/getfor clients that support the Prompts capability.Skill Tools —
tools/list/tools/callasskill_*read-only tools, ensuring visibility in marketplaces (e.g. LobeHub) that index tools only.
Tool Guides
Prompt Name | Skill Tool | Description |
|
| Capturing screenshots with pikvm_screenshot |
|
| Checking screen resolution with pikvm_get_resolution |
|
| Typing text with pikvm_type |
|
| Sending keys with pikvm_key |
|
| Sending keyboard shortcuts with pikvm_shortcut |
|
| Moving the mouse with pikvm_mouse_move |
|
| Clicking with pikvm_mouse_click |
|
| Scrolling with pikvm_mouse_scroll |
|
| Automatic mouse calibration with pikvm_auto_calibrate |
Workflow Recipes
Prompt Name | Skill Tool | Arguments | Description |
|
| — | Initialize a PiKVM session |
|
| — | Calibrate mouse coordinates |
|
|
| Find and click a UI element |
|
|
| Fill in a form on screen |
|
|
| Navigate a desktop environment |
|
| — | 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, ...KeyZNumbers:
Digit0,Digit1, ...Digit9Function keys:
F1,F2, ...F12Modifiers:
ShiftLeft,ShiftRight,ControlLeft,ControlRight,AltLeft,AltRight,MetaLeft,MetaRightSpecial:
Enter,Escape,Backspace,Tab,Space,Delete,Insert,Home,End,PageUp,PageDownArrows:
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 toolspikvm_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_calibrateCRead-onlyIdempotent
Guide for automatic mouse calibration with pikvm_auto_calibrate
Inputs: no named parameters.
skill_auto_calibrate_mouse_workflowCRead-onlyIdempotent
Step-by-step procedure for automatic mouse calibration
Inputs: no named parameters.
skill_calibrate_mouse_workflowARead-onlyIdempotent
Step-by-step procedure for calibrating mouse coordinates
Inputs: no named parameters.
skill_check_resolutionCRead-onlyIdempotent
Guide for checking screen resolution with pikvm_get_resolution
Inputs: no named parameters.
skill_click_elementCRead-onlyIdempotent
Guide for clicking with pikvm_mouse_click
Inputs: no named parameters.
skill_click_ui_element_workflowBRead-onlyIdempotent
Step-by-step procedure for finding and clicking a UI element
Inputs: element_description (required).
skill_fill_form_workflowCRead-onlyIdempotent
Step-by-step procedure for filling in a form on screen
Inputs: form_description.
skill_move_mouseCRead-onlyIdempotent
Guide for moving the mouse with pikvm_mouse_move
Inputs: no named parameters.
skill_scroll_pageCRead-onlyIdempotent
Guide for scrolling with pikvm_mouse_scroll
Inputs: no named parameters.
skill_send_keyDRead-onlyIdempotent
Guide for sending keys with pikvm_key
Inputs: no named parameters.
skill_send_shortcutDRead-onlyIdempotent
Guide for sending keyboard shortcuts with pikvm_shortcut
Inputs: no named parameters.
skill_setup_session_workflowBRead-onlyIdempotent
Step-by-step procedure for initializing a PiKVM session
Inputs: no named parameters.
skill_take_screenshotCRead-onlyIdempotent
Guide for capturing screenshots with pikvm_screenshot
Inputs: no named parameters.
skill_type_textCRead-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
Scored across 28 tools
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.
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.
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.
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
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
MCP server for AI dialogue using various LLM models via AceDataCloud
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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 npm6MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that gives AI agents direct control over QEMU virtual machines.25 npm1MIT
- AlicenseNot gradedqualityCmaintenanceMCP 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.25MIT
- AlicenseAqualityBmaintenanceAn 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.34118 PyPI19Apache 2.0