PiKVM MCP

Control one PiKVM from an MCP client such as ChatGPT Codex or Google Antigravity. It can view and crop the screen, read on-screen text, navigate BIOS, type, mount an ISO already stored on PiKVM, and operate power controls — but it is not a remote shell.

Choose one Compose file

File	Use it when	What is exposed
compose.yaml	Recommended. You have a DNS name and Cloudflare DNS.	Only Traefik on HTTPS (port 443) and its HTTP redirect (port 80). MCP itself is private inside Docker.
compose-http.yaml	You explicitly trust your LAN and do not want HTTPS.	MCP directly on port 8000, protected by bearer token and a CIDR client-network allow-list.

Do not run both files together.

The three keys

Key	Where it lives	What it allows
Bearer token	The Compose file	Connecting to MCP and reading PiKVM status.
View token	Generated on container start; shown in Docker logs	Capturing a screen image.
Control token	Generated on container start; shown in Docker logs	Keyboard, mouse, ISO and power actions.

View and control tokens are replaced whenever the PiKVM MCP container restarts. An old chat therefore loses screen/control authority after a restart. Docker logs are sensitive while those tokens are valid.

If the PiKVM URL, user, or password are incomplete, MCP exposes only pikvm_info and explains what needs configuring.

Recommended: HTTPS with Cloudflare DNS-01

You need a DNS name such as mcp.example.com, a Cloudflare API token scoped to that zone with Zone / Zone / Read and Zone / DNS / Edit, and Docker Compose on the server/LXC.

On the Docker host:

mkdir mcp-pikvm && cd mcp-pikvm
curl -fsSLO https://raw.githubusercontent.com/rovingclimber/mcp-pikvm/v0.9.2/compose.yaml

Open compose.yaml and replace every CHANGE ME value. In particular:

1. Add the PiKVM URL, username and password.
2. Replace all mcp.example.com occurrences with your DNS name, including MCP_PUBLIC_ENDPOINT.
3. Change the Traefik ipallowlist CIDR to your own LAN, for example 192.168.1.0/24.
4. Add the Cloudflare token and certificate-notification email.

Generate and insert a bearer token without printing it:

TOKEN="$(openssl rand -base64 32 | tr -d '\n')" && sed -i "s|MCP_HTTP_BEARER_TOKEN: \"CHANGE-ME-USE-A-LONG-RANDOM-TOKEN\"|MCP_HTTP_BEARER_TOKEN: \"$TOKEN\"|" compose.yaml && unset TOKEN

Then start it:

docker compose up -d
docker compose logs pikvm-mcp

The second command displays the exact MCP endpoint and the temporary view/control tokens. The HTTPS endpoint normally looks like:

https://mcp.example.com/mcp

The MCP service has no published port in this file. 127.0.0.1 is not involved: Traefik reaches MCP through Docker's private service network, and only Traefik publishes ports 80/443.

Traefik obtains and renews the certificate using Cloudflare DNS-01. It has a read-only Docker socket only to discover the labelled MCP service; the MCP container itself has no Docker socket access. Traefik’s ACME documentation

Fallback: trusted-LAN HTTP

Use this only when every network between your client and the Docker host is trusted. It is normal HTTP, so the bearer token travels unencrypted.

mkdir mcp-pikvm && cd mcp-pikvm
curl -fsSLO https://raw.githubusercontent.com/rovingclimber/mcp-pikvm/v0.9.2/compose-http.yaml

Edit the marked values, then generate the bearer token:

TOKEN="$(openssl rand -base64 32 | tr -d '\n')" && sed -i "s|MCP_HTTP_BEARER_TOKEN: \"CHANGE-ME-USE-A-LONG-RANDOM-TOKEN\"|MCP_HTTP_BEARER_TOKEN: \"$TOKEN\"|" compose-http.yaml && unset TOKEN
docker compose -f compose-http.yaml up -d

Set MCP_HTTP_ALLOWED_HOSTS to the Docker host’s actual LAN address, for example 192.168.1.139:8000. It is an HTTP Host allow-list, so it must not contain CIDR values.

Set MCP_HTTP_ALLOWED_CLIENT_NETWORKS to who may connect. It accepts CIDR ranges, for example:

192.168.0.0/24
192.168.0.0/24,10.0.0.0/8
192.168.1.0/24,fd00::/8

The HTTP file publishes 8000:8000, meaning Docker listens on the host’s network interfaces. The CIDR gate is enforced by MCP as a second check; use your host firewall as well if it has more than one network.

The endpoint is:

http://your-docker-host:8000/mcp

Connect ChatGPT Codex on Windows

First set the bearer token as a Windows user environment variable. Copy the MCP_HTTP_BEARER_TOKEN value from your Compose file, then run this in PowerShell:

[Environment]::SetEnvironmentVariable('PIKVM_MCP_BEARER_TOKEN', 'paste-the-bearer-token-here', 'User')

Completely close and reopen ChatGPT Desktop after setting it.

Use the desktop UI

In ChatGPT Desktop, go to File → Settings → Plugins → MCPs → Add server. Enter:

• URL: https://mcp.example.com/mcp — or the trusted-LAN HTTP endpoint.
• Bearer token env var: PIKVM_MCP_BEARER_TOKEN

The bearer token stays in your Windows user environment rather than in the UI configuration.

Or edit Codex configuration directly

Add this to %USERPROFILE%\.codex\config.toml (for example C:\Users\Justin\.codex\config.toml):

[mcp_servers.mcp-pikvm]
enabled = true
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "PIKVM_MCP_BEARER_TOKEN"

For an HTTP-only LAN deployment, change only the URL. Codex supports streamable HTTP servers with url and bearer_token_env_var; personal settings belong in ~/.codex/config.toml, while trusted projects may use .codex/config.toml. Codex configuration reference, MCP configuration

Start a new task and type /mcp to check the connection. Codex receives the tool names and safety guidance automatically. Begin with pikvm_status; it needs only the bearer token. Give the view/control token only when you explicitly want screen access or control.

Connect Google Antigravity

Antigravity’s remote-MCP configuration uses static HTTP headers. Its documented env object is for a local stdio server process, not for substituting values into headers of a remote serverUrl; there is no documented environment-variable reference for this bearer header. That means the bearer token is stored in the JSON file below, so keep that file private. Antigravity MCP documentation

Put this in your Antigravity MCP configuration file (commonly %USERPROFILE%\.gemini\config\mcp_config.json; use the location shown by your installed Antigravity build):

{
  "mcpServers": {
    "mcp-pikvm": {
      "serverUrl": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer paste-the-bearer-token-here"
      },
      "requiresOAuth": false
    }
  }
}

Use your HTTP endpoint instead only for a trusted LAN. Restart Antigravity after saving the file.

Operating safely

• pikvm_status is bearer-only and read-only.
• pikvm_screenshot, pikvm_screenshot_region, and on-demand pikvm_read_screen_text require the current view token. OCR is local, runs only when requested, caps its working image at roughly 1.2 megapixels, and never needs a GPU.
• Keyboard, mouse, ISO mounting/ejection, HID changes and ATX power controls require the current control token. Destructive operations also require clear confirmation text.
• For desktop work use absolute mouse mode and a fresh screenshot before coordinate actions. pikvm_move_pointer_to, pikvm_click_at, pikvm_double_click_at, and pikvm_click_drag use that screenshot ID; dragging requires CONFIRM DRAG and always releases the left button if movement fails. For BIOS/UEFI use relative mouse mode plus pikvm_move_mouse_relative and pikvm_click_mouse.

To revoke view/control authority immediately, restart the MCP service:

docker compose restart pikvm-mcp

The server deliberately does not offer arbitrary shell execution, PiKVM configuration changes, arbitrary PiKVM API calls, or media upload/download.

Moving from v0.5 or older

v0.7 removes the admin page, runtime configuration, secrets/ directory, setup script, and .env file. Make a fresh deployment directory using one Compose file above, update the Windows bearer-token environment variable, then stop the old service before starting the new one.

Reusable PiKVM API core

This repository also contains pikvm_core: a reusable authenticated PiKVM API client with no MCP or LLM dependency. The public MCP uses it, while a future trusted local runtime can import it directly. Its full-API transport and integration boundary are documented in PiKVM Core.

Development

uv sync --group dev
uv run pytest