Log inSubmit server
Aiterm MCP logo

Aiterm MCP

Drives a persistent tmux or psmux terminal and launches coding agents through MCP.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

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.

Automated check passed— started and listed 18 tools correctly (Today).

Overview

The aiterm-mcp MCP server gives an MCP client one persistent interactive terminal backed by tmux on POSIX or psmux on native Windows. It exposes PTY controls for opening, sending input to, reading from, observing, and closing sessions, plus launchers for Claude Code, Codex CLI, Grok CLI, and Cursor Agent CLI. Reach for it when an agent needs to operate a long-lived shell, nested SSH or container session, REPL, or another coding agent without a human at the terminal. Sessions can survive an MCP server or client restart because the multiplexer owns the terminal state.

Use cases

  • Drive a persistent shell across multiple MCP turns
  • Launch and coordinate coding agents from one terminal
  • Run nested SSH or container sessions
  • Automate interactive CLI workflows in CI or cron jobs

Key features

  • Persistent tmux or psmux-backed PTY sessions
  • Interactive terminal input, key, screen, and output controls
  • Unified launcher for Claude Code, Codex CLI, Grok CLI, and Cursor Agent CLI
  • Agent model discovery and in-place configuration
  • Approval and Claude turn management
  • Automated MCP client setup

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 2d ago

Recent health check succeeded.

7/7 checks healthy over the last 40d

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 12d 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 downloads16kPackage downloads in the last 30 days.
Last commit9d agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed18Callable tools this server registers over MCP.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How Aiterm MCP works

What aiterm-mcp MCP server does

The aiterm-mcp MCP server exposes one persistent interactive terminal through MCP. An MCP client can create PTY sessions, send text or key presses, read output, inspect the current screen, and close sessions. The terminal can host ordinary shells as well as nested SSH sessions, container commands, REPLs, and interactive agent interfaces.

The server also provides a common way to launch coding agents. agent_launch selects an execution harness from claude-code, codex-cli, grok-cli, or cursor-cli, while the optional model setting is passed to that harness. The launcher returns a persistent session that the calling client can continue to drive. Agent-related tools cover model discovery, in-place configuration, approval handling, and Claude turn management.

How it works

PTY sessions run through tmux on POSIX systems and psmux 3.3.8 or newer on native Windows. Because the multiplexer holds the session, terminal state can remain available after the MCP server or AI client restarts. The MCP client remains responsible for driving the terminal turn by turn; the server does not add a separate shared-memory protocol or autonomous negotiation layer.

The PTY API separates input, output, and control. Use pty_send for text, pty_key for keys such as C-c or Enter, and pty_read or pty_observe to retrieve output and screen state. Reads can use waits, markers, regular expressions, line ranges, and other selection options. pty_list reports available sessions, and diagnostics provides a server diagnostic entry point.

Setup and configuration

Install Node.js 18 or newer and a supported multiplexer. The package can be run without cloning or building with npx -y aiterm-mcp, or installed globally with npm. The repository provides aiterm-setup --json to prepare dependencies, test terminal operation, and register the MCP entry with detected client settings. On Windows, setup can prepare PowerShell 7, Git for Windows, and psmux through winget; on macOS it can prepare tmux through Homebrew; Ubuntu and Debian use apt with sudo. Other Linux distributions can use an existing tmux installation, but automatic installation stops as unsupported.

Claude Code, Claude Desktop, and Cursor can register the server with a stdio configuration that invokes npx -y aiterm-mcp. Codex driving additionally requires the Codex CLI to be installed and authenticated. After updating the package or configuration, restart the MCP client.

Tools and capabilities

The exposed interface includes:

  • PTY lifecycle and interaction: pty_open, pty_send, pty_read, pty_key, pty_close, pty_list, and pty_observe.
  • Agent execution: agent_launch, agent_models, agent_configure, agent_approval, and Claude-specific turn and approval controls.
  • Compatibility and maintenance: the legacy claude_agent launcher and diagnostics.

Agent launch options include harness, model, reasoning effort, working directory, write scope, project trust, environment variables, and optional throughline inputs. Approval tools accept an action and session context, with prompt-digest fields available where supported.

Limitations and notes

The aiterm-mcp MCP server depends on Node.js and a compatible multiplexer. Native Windows requires psmux 3.3.8 or newer; POSIX systems require tmux. It does not replace the authentication or agent loop of the selected harness, and launched agents continue to use the normal project and harness configuration available to their direct CLI.

The server is designed for programmatic MCP control rather than manual terminal operation. Codex-specific steering and hook behavior require the relevant official Codex CLI or Desktop support and separate setup options. Legacy launcher aliases remain for migration, but agent_launch is the canonical launcher interface.

Read the full README View source on GitHub

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-backed terminal on POSIX or psmux-backed terminal on native Windows. Its main tools open, drive, read, observe, and close PTY sessions, and launch Claude Code, Codex CLI, Grok CLI, or Cursor Agent CLI through a shared harness API.

Install Node.js 18 or newer and run `npx -y aiterm-mcp`, or install the package globally with npm. The provided `aiterm-setup --json` command can prepare supported terminal dependencies and register the server with detected client settings.

Yes, aiterm-mcp can be registered in Cursor with a project `.cursor/mcp.json` or a global `~/.cursor/mcp.json`. It can also launch Cursor Agent CLI through the `cursor-cli` execution harness.

It uses tmux on POSIX systems and psmux 3.3.8 or newer on native Windows. The multiplexer keeps terminal sessions persistent when the MCP server or AI client restarts.

Yes, `agent_launch` can select Claude Code, Codex CLI, Grok CLI, or Cursor Agent CLI as the execution harness. The returned session can then be driven with the PTY tools and configured with agent-specific controls.

Related MCP servers

All in Developer Tools All alternatives
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>