MCP Tools Reference

Complete tool reference for the Hyperia MCP server. Version 0.2.0.

Quick Start

Call terminal_status to see all open panes with their split labels (a, b, c...).
Use the label to target a specific pane: terminal_run(command: "ls", pane: "b")
For a full view of everything at once, use tab_snapshot.
Omit the pane parameter to target the first/focused pane.

Terminal

terminal_status

List all open terminal panes with their split labels, tab names, dimensions, and PIDs. Call this first to discover available panes and their labels.

No parameters.

Returns: {"panes": [{"id": 0, "splitLabel": "a", "tabName": "pwsh", "cols": 49, "rows": 68, "pid": 1234}, ...]}

terminal_run

Run a shell command in a pane. Sends command + Enter, waits for output, returns screen content.

command	string, required	Shell command to execute
pane	string, optional	Split label (e.g. "a", "b"). Omit for first pane.
wait_ms	number, optional	Wait before reading screen (default: 2000)

terminal_keys

Type raw keystrokes into a pane. Use \n for Enter, \t for Tab. Good for interactive prompts.

keys	string, required	Keystrokes to type
pane	string, optional	Split label

terminal_screen

Read the current screen content of a pane. Returns the visible terminal text.

pane

string, optional

Split label

tab_snapshot

Read all pane screens at once. Returns labeled output for every visible pane. Best for getting a holistic view across splits.

No parameters.

terminal_split

Split the currently focused pane. New panes get the next available letter labels. Call terminal_status after to see updated labels.

direction

string, optional

"horizontal" (top/bottom) or "vertical" (left/right, default)

terminal_focus

Focus a specific pane by its split label.

pane

string, required

Split label (e.g. "a", "b", "c")

terminal_new_tab

Open a new tab. Optionally run a startup command in it once the shell is ready.

command

string, optional

Command to run after tab opens (e.g. "cd /project && claude")

terminal_close

Close the currently focused pane.

No parameters.

shell_state

Analyze all pane screens and detect their state: idle (at prompt), dialog (waiting for input), running (command in progress), or empty.

No parameters.

shell_confirm

Auto-handle common shell prompts (trust dialogs, y/n confirmations, "press enter to continue") on one or all panes.

pane

number, optional

Pane index. Omit for all panes.

Agent

agent_status

Set the agent status light on a tab. Shows a colored dot indicator: green (connected), red (working), amber (wants input).

connected	bool, required	Agent connected state
working	bool, optional	Agent actively working
label	string, optional	Short label (e.g. "thinking...")
human_percent	number, optional	0-100 human interaction level
pane	number, optional	Pane index to target

auto_describe

Auto-describe a pane using local ollama. Reads screen content, generates a short description, and stores it on the tab.

pane

number, optional

Pane index (default: 0)

Voice (Auracle)

voice_status

Get voice/mic (Auracle) status: running, service health, exe path.

voice_start

Start voice/mic capture. Transcripts are typed into the focused pane.

voice_stop

Stop voice/mic capture.

voice_toggle

Toggle voice/mic capture on/off.

Styles

style_list

List all styles in the Hyperia config.

style_create

Create or clone a style. Optionally clone from existing and apply overrides.

name	string, required	Name for the new style
clone_from	string, optional	Source style to clone
overrides	object, optional	{"fontSize": 16, "backgroundColor": "#1a1a2e"}

style_delete

Delete a style by name. Cannot delete "default".

name

string, required

Style name to delete

Telemetry

telemetry_toggle

Enable or disable telemetry collection.

enabled

bool, required

Enable or disable

telemetry_snapshot

Get a telemetry snapshot at window or pane level.

level	string, optional	"window" or "pane" (default: window)
pane_uid	string, optional	Pane UID (when level is "pane")

telemetry_record

Record a telemetry event (file op, network, tokens) for a pane.

telemetry_reset

Reset all telemetry counters.

Stream Deck

deck_info

Get Stream Deck device info and state.

deck_button_image

Set a button image from base64 PNG/JPEG. Key 0-7.

deck_button_color

Set a button to a solid RGB color. Key 0-7.

deck_touchstrip

Set touchstrip text (scrolls if long) or base64 image (800x100).

deck_brightness

Set brightness 0-100.

deck_knob

Configure an encoder knob. Encoder 0-3, mode: tabs/brightness/volume/custom.

deck_screenshot

Take a screenshot of the Stream Deck. Returns base64 PNG.

Logs

sidecar_logs

Read sidecar logs.

Configuration

One-line install — drop the MCP config into your project:

curl -o .mcp.json https://hyperia.nuts.services/mcp.json

Or add manually to your .mcp.json:

{
  "mcpServers": {
    "hyperia": {
      "command": "hyperia-sidecar",
      "args": ["--mcp"]
    }
  }
}

The sidecar binary is bundled with Hyperia at resources/sidecar/hyperia-sidecar.exe. Use the full path if it's not in your PATH.

Current config: hyperia.nuts.services/mcp.json