Aiterm MCP logo

Aiterm MCP

Persistent MCP terminal for driving local shells, nested SSH or containers, and interactive coding agents.

Install Aiterm MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "aiterm-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "aiterm-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— the server itself is confirmed live (we called its tools/list endpoint). The stdio install command is a separate, ongoing check.

Overview

aiterm-mcp connects MCP clients to one persistent tmux-backed terminal, using psmux 3.3.8+ on native Windows. It can launch Claude Code, Codex CLI, Grok CLI, or Cursor Agent sessions, then send turns, inspect state, handle approvals, and retrieve transcripts through structured tools. Reach for it when an agent needs a durable interactive shell, nested SSH or container workflows, or programmatic delegation to another coding agent. Sessions remain available across MCP server and client restarts while the backend stays running.

Use cases

  • Drive a persistent shell across client or server restarts
  • Run SSH and container sessions inside one MCP terminal
  • Launch coding agents for delegated implementation or review
  • Dispatch non-blocking agent turns from an orchestration loop
  • Retrieve reduced terminal output or completed agent transcripts

Key features

  • Persistent tmux or psmux-backed PTY sessions
  • Structured launch of Claude, Codex, Grok, and Cursor agents
  • Non-blocking agent dispatch with parent delivery
  • Token-reduced incremental terminal reads
  • Digest-bound Claude and Codex approval handling
  • Machine-readable diagnostics and session observation

Tools18

What Aiterm MCP lets your agent do. Expand a tool for its parameters.

Verified live~8.4k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked

Recent health check succeeded.

13/13 checks healthy over the last 64d

What it can do

From the 18 tools this server returned when we ran it.

Handles credentials · 2Makes network requests · 1Read-only tools · 18
Network at startup3 connections
Files written at startupNone
Install scriptsNone
npm provenanceSigned build
Package age142 days
Maintainers1

Observed 2026-10-22 in an isolated sandbox. A description of reach, not a security audit.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 3d ago via OSV.dev · aiterm-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars6Stargazers on the source repository.
npm downloads25kPackage downloads in the last 30 days.
Last commit2d agoMost recent push to the default branch.
Tools exposed18Callable tools this server registers over MCP.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How Aiterm MCP works

What aiterm-mcp does

aiterm-mcp exposes a persistent interactive terminal through MCP. On POSIX systems it uses tmux; on native Windows it uses psmux 3.3.8 or newer. The terminal can run ordinary commands, SSH sessions, container commands, REPLs, and interactive TUIs. Remote access is performed inside the opened terminal, for example by sending an ssh command, rather than through a separate remote-session tool.

The server also provides one standard agent launcher. agent_launch can start Claude Code, Codex CLI, Grok CLI, or Cursor Agent in a persistent terminal session. The execution harness owns the agent loop, authentication, hooks, and transcript, while the selected model remains a separate setting. Launched agents inherit the normal CLI environment, including the relevant home directory, working directory, project configuration, MCP settings, plugins, skills, permissions, and trust configuration.

How it works

Open a terminal with pty_open, which returns a session_id. Use pty_send for text input, pty_key for control keys such as C-c or Enter, and pty_read to retrieve output. Reads normally return only content since the previous read and apply output reduction such as control-character removal, repetition compression, and head-and-tail folding.

Agent turns are dispatched without blocking the parent tool call. Claude Code and Codex parent sessions can receive completed answers automatically when the required hooks are configured. Cursor can receive parent-delivery data and a background wait process. Other callers can use the returned wait-process instructions or retrieve a completed agent transcript with pty_read(agent_transcript: true). claude_turn provides a structured recovery surface for durable Claude operations.

pty_observe reports session, pane, harness, process, screen-change, and CPU-activity state without returning screen text or the process argument vector. pty_list shows active sessions, their foreground command, attachment state, dimensions, and agent information.

Setup and configuration

Install the published package globally and run the setup command:

Terminal
npm install -g aiterm-mcp@latest
aiterm-setup --json

The setup process can prepare supported terminal dependencies, test terminal operation, register the MCP entry, and configure parent-delivery hooks. Windows setup uses PowerShell 7, Git for Windows, and psmux; macOS uses Homebrew for tmux; Ubuntu and Debian use apt for tmux. Other Linux systems can use an existing tmux installation, but automatic dependency installation stops as unsupported.

The package requires Node.js 18 or newer. A direct stdio registration uses npx -y aiterm-mcp. Claude Code, Claude Desktop, and Cursor can each register that command in their MCP configuration. Codex interaction also requires the Codex CLI to be installed and authenticated. Use aiterm-setup --hooks-only when another system owns MCP registration but Claude Code or Cursor parent hooks still need configuration.

Tools and capabilities

  • Open, send input to, read from, observe, list, and close persistent PTY sessions.
  • Send named control keys and receive structured close receipts.
  • Launch and configure Claude Code, Codex, Grok, or Cursor agent sessions.
  • Query harness-provided model and reasoning-effort catalogs without sending a prompt.
  • Start, inspect, or cancel official CLI authentication flows while credentials remain owned by the CLI.
  • Inspect and answer Codex approval dialogs with one-time digest-bound decisions.
  • Inspect and answer correlated Claude approval prompts with safe single Yes/No responses.
  • Return machine-readable diagnostics without exposing PTY content, credentials, paths, or environment values.

Limitations and notes

The server manages one persistent terminal per opened session, and closing a session discards its log and read position. A closed-session retry is safe and returns a structured receipt. Control-key acceptance indicates that input was accepted; it does not confirm that a process stopped or that a conversation was preserved.

Parent delivery depends on the relevant hook registration and client behavior. Codex desktop conversations may sleep when not viewed, and waking behavior differs by platform. The wait_command value is intended for human-readable compatibility output, not as a process boundary. For automated completion handling, use the supplied wait-process executable and arguments without blocking the parent turn.

The older Claude, Codex, and Grok launcher aliases remain for migration, while new integrations should use agent_launch. Authentication success only indicates that the official CLI is authenticated; it does not guarantee that an agent session has been launched.

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Aiterm MCP

aiterm-mcp is an MCP server that connects AI clients to a persistent tmux or psmux terminal and provides tools for opening, driving, reading, observing, and closing sessions. It can also launch Claude Code, Codex CLI, Grok CLI, or Cursor Agent sessions, configure models, handle approvals, and retrieve completed agent transcripts.

Install it with `npm install -g aiterm-mcp@latest`, then run `aiterm-setup --json`. The setup command prepares supported terminal dependencies and registers the MCP entry. A direct stdio configuration can instead launch `npx -y aiterm-mcp`.

Yes, aiterm-mcp can be registered in Cursor through `.cursor/mcp.json` or the global Cursor MCP configuration. Cursor parent delivery requires its configured hook support, and Cursor Agent can also be selected as the execution harness through `agent_launch`.

aiterm-mcp can launch Claude Code, Codex CLI, Grok CLI, and Cursor Agent through `agent_launch`. The harness and model are separate settings, so Cursor Agent can select supported GPT, Claude, or Grok models while retaining Cursor’s session and completion behavior.

Yes, sessions survive MCP server or client restarts because the backend terminal remains resident. POSIX systems use tmux, while native Windows requires psmux 3.3.8 or newer. Closing a session explicitly removes its log and read position.

Related MCP servers

Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewAiterm MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/aiterm-mcp?style=directory)](https://allmcps.com/mcp/aiterm-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/aiterm-mcp"><img src="https://allmcps.com/api/badge/aiterm-mcp?style=directory" alt="Aiterm MCP on AllMCPs" /></a>