node-terminal-mcp

hazzel-cn/node-terminal-mcp

3.3

If you are the rightful owner of node-terminal-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The @hazzel-cn/node-terminal-mcp is a Model Context Protocol (MCP) server designed for managing terminal/PTY sessions, enabling AI agents to interact with terminal environments seamlessly.

Tools
7
Resources
0
Prompts
0

@hazzel-cn/node-terminal-mcp

npm version GitHub

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)

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

From source

git clone https://github.com/hazzel-cn/node-terminal-mcp.git
cd node-terminal-mcp
npm install
npm run build

Building

npm run build

Development

npm run dev

Configuration

Gemini CLI

Option A: Using stdio transport (default)

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

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

{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "bash",
      "args": ["-c", "npx -y @hazzel-cn/node-terminal-mcp"],
      "env": {}
    }
  }
}

Google ADK

Option A: Using npx (recommended)

{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "npx",
      "args": ["-y", "@hazzel-cn/node-terminal-mcp@latest"],
      "env": {}
    }
  }
}

Option B: Using global installation (recommended)

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

{
  "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:
{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "npx",
      "args": ["-y", "@hazzel-cn/node-terminal-mcp@latest"],
      "env": {},
      "timeout": 30000
    }
  }
}
  1. Install globally:
npm install -g @hazzel-cn/node-terminal-mcp

{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "node-terminal-mcp",
      "args": [],
      "env": {}
    }
  }
}
  1. Use bash wrapper:
{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "bash",
      "args": ["-c", "npx -y @hazzel-cn/node-terminal-mcp@latest"],
      "env": {}
    }
  }
}

Links

License

MIT License - see file for details.