Node Terminal

MCP server: terminal/PTY sessions for AI Agents (node-pty + xterm headless)

javascript

2

GitHub Stars

javascript

Language

4 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

This MCP server lets AI agents create and manage multiple PTY terminal sessions, send commands, and read real-time output. It supports bidirectional communication, session management, and are compatible with stdio transports for efficient control of terminal environments.

How to use

You connect to the MCP server from your client and use its terminal functions to create, feed, and monitor terminal sessions. You can open several terminals at once, resize them, and close them as needed. Use the provided tools to send input, simulate keystrokes, read terminal output, and manage terminal lifecycles in real time.

How to install

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

If you encounter connection issues with ADK or need a longer timeout, you can extend the timeout in the same configuration structure.

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

If you prefer running via a local brew or wrapper, you can wrap the command in a shell invocation as shown.

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

Configuration

The server can be configured through MCP client settings using different transport options. Choose the stdio transport (default) to run the MCP server locally via a command like npx. If you need a persistent wrapper or to troubleshoot connection issues, you can wrap the command in a shell script as shown above.

Troubleshooting

If you see a Connection Closed error with ADK, ensure you are using the latest MCP version and consider increasing the timeout. You can also install the package globally and invoke the local binary, or use a bash wrapper to run the MCP with a shell command.

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

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

Available tools

create_terminal

Create a new terminal session to manage inputs and commands programmatically.

write_to_terminal

Send input text to a specific terminal session.

send_key_to_terminal

Send special keys (like arrows, Ctrl, etc.) to a terminal session.

read_from_terminal

Read the output from a terminal session in real time.

resize_terminal

Resize the dimensions of a terminal session.

list_terminals

List all active terminal sessions.

close_terminal

Close a terminal session and release resources.