Package Exports

@hazzel-cn/node-terminal-mcp
@hazzel-cn/node-terminal-mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@hazzel-cn/node-terminal-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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)

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:

Use the latest version:

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

Install globally:

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

{
  "mcpServers": {
    "node-terminal-mcp": {
      "command": "node-terminal-mcp",
      "args": [],
      "env": {}
    }
  }
}

Use bash wrapper:

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

License

MIT License - see LICENSE file for details.