MCP Shell Server

A Model Context Protocol (MCP) server providing an interactive terminal interface via Pseudo-Terminal (PTY) emulation. This server enables LLMs to execute shell commands, manage persistent sessions, and monitor real-time output within a controlled environment.

Features

• PTY Emulation: Provides a full pseudo-terminal environment for accurate command execution and handling of interactive processes.
• Session Persistence: Supports multiple concurrent shell instances identified by unique terminal IDs.
• Incremental Output: Buffered output management allows clients to poll for new data without losing session state.
• Configurable Environment: Customizable shell paths and network security parameters.

Installation

Pre-built Binaries

Compiled executables for supported architectures are available in the Releases section of the GitHub repository.

From Source

Clone and build:

git clone https://github.com/eja/mcp-shell.git
cd mcp-shell
make all

Usage

Launch the server with the desired configuration:

./bin/mcp-shell --port 35248 --token <SECRET_TOKEN> --shell /bin/bash

Configuration Options

| Option | Description | Default | | :--- | :--- | :--- | | --host | Network interface to bind the server to | localhost | | --port | Network port for the server | 8081 | | --token | Optional bearer token for request authentication | (empty) | | --shell | Path to the shell executable to be used | /bin/sh | | --cors | Enable Cross-Origin Resource Sharing headers | false | | --log | Enable standard error logging | false | | --log-level | Logging verbosity (1=Error, 2=Warn, 3=Info, 4=Debug) | 3 | | --log-file | Path to a file for log output | (stderr) |

MCP Toolset

The server exposes the following tools to MCP-compatible clients:

• open_terminal: Spawns a new shell instance and returns a unique terminal_id.
• run_command: Dispatches input to a specific terminal session.
• read_output: Retrieves all accumulated stdout and stderr since the last read for a given session.
• close_terminal: Shuts down the PTY process and cleans up associated system resources.

Security Considerations

• Remote Execution: This server allows the execution of arbitrary code on the host system. It must be deployed within a secure, isolated environment (e.g., Docker container or dedicated VM).
• Authentication: Usage of the --token flag is strongly recommended to prevent unauthorized access.
• CORS: Enabling --cors exposes the server to potential browser-based attacks. Use only if the server is adequately protected by a firewall or reverse proxy.
• Privileges: The server should never be executed with root/administrative privileges.