mcp-shell

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.