Skip to main content
Glama

Node Terminal MCP

by hazzel-cn
GitHub
JavaScript
MIT License
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables AI agents to interact with terminal environments through multiple concurrent PTY sessions. Supports cross-platform terminal operations including command execution, session management, and real-time communication.

  1. Features
    1. Installation
      1. From npm (recommended)
      2. From source
    2. Building
      1. Development
        1. Configuration
          1. Gemini CLI
          2. Google ADK
        2. Usage
          1. Architecture
            1. Requirements
              1. Troubleshooting
                1. ADK "Connection Closed" Issue
              2. Links
                1. License

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/hazzel-cn/node-terminal-mcp'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server