@hazzel-cn/node-terminal-mcp

MCP server for terminal/PTY sessions using node-pty and xterm headless, designed for AI agents to interact with terminal environments.

Features

• Multiple Terminal Sessions: Create and manage multiple concurrent terminal sessions

• AI Agent Integration: Send commands and read output from terminals programmatically

• Cross-Platform: Works on Windows, macOS, and Linux

• Real-time Communication: Bidirectional communication between AI agents and terminal sessions

• Session Management: Create, resize, and close terminal sessions as needed

• Stdio Compatible: Optimized for stdio transport with proper error handling and signal management

Installation

From npm (recommended)

From source

Building

Development

Configuration

Gemini CLI

Option A: Using stdio transport (default)

Option B: If you get "Connection closed" errors with ADK, try this:

Option C: Alternative workaround for persistent connection issues:

Google ADK

Option A: Using npx (recommended)

Option B: Using global installation (recommended)

Usage

The server provides the following MCP tools:

• create_terminal: Create a new terminal session

• write_to_terminal: Send input to a terminal session

• send_key_to_terminal: Send special keys to a terminal session

• read_from_terminal: Read output from a terminal session

• resize_terminal: Resize a terminal session

• list_terminals: List all active terminal sessions

• close_terminal: Close a terminal session

Architecture

• TerminalManager: Manages multiple terminal sessions using node-pty

• PTY Integration: Uses node-pty for terminal emulation and process management

• MCP Server: Provides standardized interface for AI agents

Requirements

• Node.js 18+

• Compatible with MCP (Model Context Protocol) clients

Troubleshooting

ADK "Connection Closed" Issue

If you're experiencing "Connection closed" errors with Google ADK, this is a known issue with stdio transport. Try these solutions:

1. Use the latest version:

2. Install globally:

3. Use bash wrapper:

Links

• npm: https://www.npmjs.com/package/@hazzel-cn/node-terminal-mcp

• GitHub: https://github.com/hazzel-cn/node-terminal-mcp

• Issues: https://github.com/hazzel-cn/node-terminal-mcp/issues

License

MIT License - see LICENSE file for details.