README.md•4.42 kB
# @hazzel-cn/node-terminal-mcp
[](https://www.npmjs.com/package/@hazzel-cn/node-terminal-mcp)
[](https://github.com/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)
```bash
npm install -g @hazzel-cn/node-terminal-mcp
```
### From source
```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
### Gemini CLI
**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": {}
}
}
}
```
### Google ADK
**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
### 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:**
```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](LICENSE) file for details.