Node Terminal MCP

# @hazzel-cn/node-terminal-mcp [](https://www.npmjs.com/package/@hazzel-cn/node-terminal-mcp) [](https://github.com/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) ```bash npm install -g @hazzel-cn/node-terminal-mcp ``` ### From source ```bash git clone https://github.com/hazzel-cn/node-terminal-mcp.git cd node-terminal-mcp npm install npm run build ``` ## Building ```bash npm run build ``` ## Development ```bash npm run dev ``` ## Configuration ### Gemini CLI **Option A: Using stdio transport (default)** ```json { "mcpServers": { "node-terminal-mcp": { "command": "npx", "args": ["-y", "@hazzel-cn/node-terminal-mcp@latest"], "env": {} } } } ``` **Option B: If you get "Connection closed" errors with ADK, try this:** ```json { "mcpServers": { "node-terminal-mcp": { "command": "npx", "args": ["-y", "@hazzel-cn/node-terminal-mcp@latest"], "env": {}, "timeout": 30000 } } } ``` **Option C: Alternative workaround for persistent connection issues:** ```json { "mcpServers": { "node-terminal-mcp": { "command": "bash", "args": ["-c", "npx -y @hazzel-cn/node-terminal-mcp"], "env": {} } } } ``` ### Google ADK **Option A: Using npx (recommended)** ```json { "mcpServers": { "node-terminal-mcp": { "command": "npx", "args": ["-y", "@hazzel-cn/node-terminal-mcp@latest"], "env": {} } } } ``` **Option B: Using global installation (recommended)** ```bash npm install -g @hazzel-cn/node-terminal-mcp ``` ```json { "mcpServers": { "node-terminal-mcp": { "command": "node-terminal-mcp", "args": [], "env": {} } } } ``` ## 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:** ```json { "mcpServers": { "node-terminal-mcp": { "command": "npx", "args": ["-y", "@hazzel-cn/node-terminal-mcp@latest"], "env": {}, "timeout": 30000 } } } ``` 2. **Install globally:** ```bash npm install -g @hazzel-cn/node-terminal-mcp ``` ```json { "mcpServers": { "node-terminal-mcp": { "command": "node-terminal-mcp", "args": [], "env": {} } } } ``` 3. **Use bash wrapper:** ```json { "mcpServers": { "node-terminal-mcp": { "command": "bash", "args": ["-c", "npx -y @hazzel-cn/node-terminal-mcp@latest"], "env": {} } } } ``` ## 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](LICENSE) file for details.