@hazzel-cn/node-pty-mcp

MCP server for interactive terminal operations using node-pty with proper terminal emulation via @xterm/headless.

Features

• True Terminal Emulation: Uses @xterm/headless for proper TUI application support
• Interactive Terminal Sessions: Create and manage persistent terminal sessions
• Real-time Screen Reading: Read current terminal screen content with proper rendering
• TUI Application Support: Optimized for vim, nano, htop, and other interactive applications
• Session Management: List, resize, and kill terminal sessions
• MCP Protocol: Full Model Context Protocol support with stdio transport

Available Tools

• create_terminal_session - Create a new terminal session
• list_terminal_sessions - List all active terminal sessions
• send_terminal_input - Send text input to a terminal
• send_terminal_key - Send special keys (Enter, Tab, Escape, Ctrl+C, etc.)
• read_terminal_screen - Read the current screen content (proper TUI rendering)
• resize_terminal_session - Resize terminal dimensions
• kill_terminal_session - Terminate a terminal session

Installation & Configuration

Quick Start (Recommended)

Using npx - no installation required:

{
  "mcpServers": {
    "node-pty-terminal": {
      "command": "npx",
      "args": ["--yes", "--quiet", "@hazzel-cn/[email protected]"],
      "timeout": 180000
    }
  }
}

Google ADK Configuration

For Google ADK, use the npx configuration above. The server is optimized for ADK with:

• No stdout noise (only MCP protocol frames)
• All logs go to stderr
• Immediate MCP handshake
• Process stays alive for long-running sessions
• Proper timeout handling (>= 120000ms recommended)

Manual Installation

npm install -g @hazzel-cn/node-pty-mcp

Then configure:

{
  "mcpServers": {
    "node-pty-terminal": {
      "command": "node-pty-mcp",
      "timeout": 10000
    }
  }
}

Usage Notes

• stdout is reserved for MCP frames - all logs go to stderr
• First-time npx may take longer - use timeout >= 120000ms
• TUI applications work properly - vim, nano, htop render correctly
• Terminal emulation - proper ANSI/CSI escape sequence handling
• Session persistence - terminals stay alive until explicitly killed

Development

npm run dev          # Development mode with hot reload
npm run build        # Build for production
npm run prepublishOnly # Build and set executable permissions

License

MIT License - see LICENSE file for details.