Unterm

What the Unterm MCP server does

The Unterm MCP server makes a running Unterm terminal controllable by external agents. Its MCP surface covers terminal operations such as spawning shells, sending commands, reading pane state, taking screenshots, and recording sessions. It also exposes Agent Cockpit functions for observing and coordinating agents that are already running in terminal panes.

The terminal can identify agent activity and states such as working, waiting for you, idle, or done. Through the cockpit API and CLI, an orchestrator can inspect the waiting queue, launch fleets of agents in separate git worktrees, review their changes, verify results, merge accepted work, discard changes, or retry a failed fleet member.

How it works

Every Unterm window starts a local MCP server alongside its local Web Settings server. The MCP endpoint uses line-delimited JSON-RPC over TCP, listens only on 127.0.0.1, and requires an authentication token. There is no cloud round trip for the core terminal control path.

Running instances receive NATO-style names such as alpha or bravo. Each instance writes its endpoint ports and authentication token to ~/.unterm/instances/<name>.json, allowing an agent or script that manages multiple windows to discover them. The API includes capability and risk information, expiring leases, isolated workspaces, approvals, and a hash-chained audit trail. These controls matter when an orchestrator must limit where commands run or provide verifiable task evidence.

Agent sessions can carry caller-provided task IDs and expose what an agent said, what it requested to run, and how it finished. Fleet work is placed in separate git worktrees, while Review checkpoints changes before they affect the main repository. Verification can use inferred project commands or a supplied validation command, and merging is gated on a passing verification unless an audited force override is used.

Setup and configuration

Install Unterm from a GitHub Release artifact for macOS, Debian or Ubuntu, other Linux distributions, or Windows.

Connection details are discovered from the instance files under ~/.unterm/. Clients must use the recorded endpoint and authentication token. Settings such as theme, language, and unterm.conf are configured through Web Settings, unterm-cli, or the configuration file rather than through MCP.

Tools and capabilities

Supported capability areas include:

• Shell and pane control, command execution, pane-state reads, scrolling screenshots, and session recording.
• Agent state inspection, Inbox operations, fleet launch, review, verification, merge, rollback, and retry.
• Capability publication through terminal.manifest, approvals, leases, workspace boundaries, and evidence artifacts.
• Multi-instance discovery through the local instance directory.

The CLI provides related commands such as agent status, agent inbox, fleet launch, review verify, and review list. MCP and CLI expose the cockpit so an orchestrating agent can manage it without a person operating the terminal directly.

Limitations and notes

Unterm is a desktop terminal application, not a standalone remote service.

Claude Code, Codex, Gemini CLI, Cursor, and Aider are named as clients or agents that can use the same JSON-RPC surface. Theme, language, and unterm.conf are outside MCP.