@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

$3

``bash
npm install -g @hazzel-cn/node-terminal-mcp
`

$3

`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

$3

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": {}
}
}
}
`

$3

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

$3

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 file for details.