Node.js Terminal MCP (winterm-mcp)

A Node.js implementation of a terminal MCP (similar to winterm) using the official MCP SDK, executing commands asynchronously using node-pty.

Features

• Asynchronous command execution with token-based status tracking
• Support for PowerShell, CMD, and arbitrary executables
• Cross-platform terminal emulation using node-pty
• MCP-compatible interface using official @modelcontextprotocol/sdk
• Automatic executable path resolution from system PATH
• Timeout handling and error management
• Real-time output streaming for long-running commands
• NEW: Interactive command support with send_command_input
• NEW: Command termination with terminate_command
• NEW: Enhanced status queries with enhanced_query_command_status
• NEW: Real-time PTY interaction capabilities
• NEW: Automatic ANSI escape sequence cleaning for clean output
• NEW: Enhanced error messages with detailed context

Installation

npm install
npm run build

Usage

MCP Server

The MCP server provides the following tools:

1. run_command: Execute a command in the terminal
2. query_command_status: Query the status of a previously submitted command
3. enhanced_query_command_status: Enhanced status query with streaming support
4. send_command_input: Send input to a running interactive command
5. terminate_command: Terminate a running command
6. get_version: Get version information

Configuration Example

To use this MCP in a configuration similar to other MCP services, add the following to your configuration:

{
  "mcpServers": {
    "winterm-mcp": {
      "command": "node",
      "args": [
        "path/to/winterm-mcp/dist/index.js"
      ],
      "env": {
        "NODETERMINAL_POWERSHELL_PATH": "C:\\CustomPath\\powershell.exe",
        "NODETERMINAL_CMD_PATH": "C:\\CustomPath\\cmd.exe",
        "NODETERMINAL_LOG_LEVEL": "info"
      }
    }
  }
}

For environments with restricted access to system paths, you can use npx to run the package:

{
  "mcpServers": {
    "winterm-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "winterm-mcp"
      ],
      "env": {
        "NODETERMINAL_POWERSHELL_PATH": "C:\\WINDOWS\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
        "NODETERMINAL_CMD_PATH": "C:\\WINDOWS\\system32\\cmd.exe"
      }
    }
  }
}

Tool: run_command

Execute a command in the terminal. Returns a token for tracking the command.

Parameters:

• command (string, required): The command to execute
• executable (string, optional): Path to executable (for arbitrary executables)
• args (array of strings, optional): Arguments for the executable
• shell_type (string, optional): Type of shell to use - 'powershell', 'cmd', or 'executable' (default: 'executable')
• timeout (integer, optional): Timeout in seconds, 1-3600 (default: 30)
• working_directory (string, optional): Working directory for the command
• enable_streaming (boolean, optional): Enable real-time output streaming (default: false)

Example:

{
  "command": "echo Hello World",
  "shell_type": "powershell",
  "timeout": 30
}

Tool: query_command_status

Query the status of a previously submitted command using its token.

Parameters:

• token (string, required): The token returned by run_command

Returns:

• status: Command status ('pending', 'running', 'completed', 'failed')
• stdout: Standard output
• stderr: Standard error output
• exit_code: Exit code (null if still running)
• execution_time: Execution time in seconds

Tool: enhanced_query_command_status

Enhanced status query with streaming support for a previously submitted command.

Parameters:

• token (string, required): The token returned by run_command
• since_timestamp (number, optional): Only return output since this timestamp (for streaming)

Returns:

• Same as query_command_status, with additional streaming support

Tool: send_command_input

Send input to a running interactive command process.

Parameters:

• token (string, required): The token of the running command
• input (string, required): Input to send to the command
• append_newline (boolean, optional): Whether to append newline to input (default: true)

Returns:

• success: Boolean indicating if input was sent successfully
• message: Error message if unsuccessful
• token: The command token

Example:

{
  "token": "abc123...",
  "input": "echo Hello",
  "append_newline": true
}

Tool: terminate_command

Terminate a running command process.

Parameters:

• token (string, required): The token of the running command

Returns:

• success: Boolean indicating if termination was successful
• message: Error message if unsuccessful
• token: The command token

Example:

{
  "token": "abc123..."
}

Tool: get_version

Get version information of the terminal MCP service.

Parameters: None

Returns:

• version: Service version
• service_status: Service status
• node_version: Node.js version
• platform: Operating system platform
• arch: System architecture

Environment Variables

The following environment variables can be configured:

• WINTERM_POWERSHELL_PATH or NODETERMINAL_POWERSHELL_PATH: Custom path to PowerShell executable
• WINTERM_CMD_PATH or NODETERMINAL_CMD_PATH: Custom path to CMD executable
• NODETERMINAL_LOG_LEVEL: Logging level

Environment Variable Usage

When running in restricted environments or when the default shell paths are not accessible, you can specify custom paths using environment variables:

{
  "mcpServers": {
    "winterm-mcp": {
      "command": "node",
      "args": ["path/to/winterm-mcp/dist/index.js"],
      "env": {
        "NODETERMINAL_POWERSHELL_PATH": "C:\\CustomPath\\powershell.exe",
        "NODETERMINAL_CMD_PATH": "C:\\CustomPath\\cmd.exe",
        "NODETERMINAL_LOG_LEVEL": "debug"
      }
    }
  }
}

Troubleshooting with Environment Variables

If you encounter "Executable not found" errors:

1. Set NODETERMINAL_POWERSHELL_PATH to the full path of powershell.exe
2. Set NODETERMINAL_CMD_PATH to the full path of cmd.exe
3. Ensure the paths are accessible and you have read/execute permissions

Output Cleaning

The MCP server automatically cleans ANSI escape sequences from command output to provide clean, readable text. This includes:

• Color codes and text formatting
• Cursor movement sequences
• Screen clearing commands
• Window title settings

If you need raw output with ANSI codes preserved, you can modify the stripAnsiCodes function in the source code.

Error Handling

The MCP server provides detailed error messages to help diagnose issues:

Common Error Types

1. Executable not found (ENOENT)

   • Error: Executable not found: <path>. Please check if the file exists and you have permission to access it.
   • Solution: Set the appropriate environment variable (NODETERMINAL_POWERSHELL_PATH or NODETERMINAL_CMD_PATH)

2. Permission denied (EACCES)

   • Error: Permission denied: <executable>. Please check file permissions.
   • Solution: Check file permissions and ensure the user has execute rights

3. Operation not permitted (EPERM)

   • Error: Operation not permitted: <executable>. Please run with appropriate privileges.
   • Solution: Run with elevated privileges if necessary

4. Command timeout

   • Error: Command timed out after X seconds
   • Solution: Increase the timeout parameter or optimize the command

Error Response Format

{
  "status": "completed",
  "exit_code": -1,
  "stdout": "",
  "stderr": "Executable not found: cmd.exe. Please check if the file exists and you have permission to access it.",
  "execution_time": 1234
}

Supported Shell Types

• powershell: Execute command using PowerShell (recommended for cleaner output)
• cmd: Execute command using CMD (may show DOSKEY warnings, PowerShell recommended)
• executable: Execute arbitrary executable with arguments

Shell Type Recommendations

PowerShell is recommended for most use cases because:

• Cleaner output without DOSKEY warnings
• Better error handling
• More consistent behavior across different Windows versions

CMD may show a harmless DOSKEY warning at the start of output:

'DOSKEY' is not recognized as an internal or external command,
operable program or batch file.

This warning does not affect command execution but can be avoided by using PowerShell.

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start the MCP server
npm start

# Run tests
npm test

License

MIT