NPCterm: Full PTY Terminal Emulator for AI Agents via MCP

NPCterm is a headless, in-memory full PTY terminal emulator for AI agents, exposed via MCP (Model Context Protocol). It gives AI agents full terminal access, not just bash, allowing them to spawn shells, run arbitrary commands, read screen output, send keystrokes, and interact with TUI applications.

Key Features

• Full ANSI/VT100 terminal emulation with PTY spawning via portable-pty
• 15 MCP tools for complete terminal control over JSON-RPC stdio
• Process state detection – knows when a command is running, idle, waiting for input, or exited
• Event system – ring buffer of terminal events (CommandFinished, WaitingForInput, Bell, etc.)
• AI-friendly coordinate overlay for precise screen navigation
• Mouse, selection, and scroll support for interacting with TUI applications
• Multiple concurrent terminals with short 2-character IDs

Example MCP Flow

The source provides a concrete example of using NPCterm to open and quit Vim:

// 1. Create a terminal
// -> terminal_create {}
// <- {"id": "a0", "cols": 80, "rows": 24}

// 2. Open vim
// -> terminal_send_keys {"id": "a0", "input": [{"text": "vim"}, {"key": "Enter"}]}
// <- {"success": true}
// 3. Read the screen to confirm vim is open
// -> terminal_show_screen {"id": "a0"}
// <- ~ VIM - Vi IMproved
// <- ~ version 9.2.250
// <- ~ by Bram Moolenaar et al.
// <- ~ type :q<Enter> to exit
// <- ...
// 4. Quit vim
// -> terminal_send_keys {"id": "a0", "input": [{"text": ":q"}, {"key": "Enter"}]}
// <- {"success": true}

The source includes a warning: "Use with precautions. A terminal is an unrestricted execution environment." This tool is effectively equivalent to giving an AI agent access to a computer.

The project is available on GitHub at github.com/alejandroqh/npcterm.