Home / MCP / MCP Terminal Server

MCP Terminal Server

High-performance MCP server enabling secure terminal execution via HTTP and stdio transports with persistent shell sessions.

8stars

View on GitHub

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
    "mcpServers": {
        "mcp_terminal": {
            "url": "http://localhost:8080/mcp"
        }
    }
}

You can run a high-performance MCP Terminal Server that executes terminal commands securely, supports both an HTTP transport and traditional stdio, and preserves shell state across commands. This guide walks you through using the server with an MCP client, installing it, and understanding key configuration and security considerations.

How to use

You will interact with the server through an MCP client that speaks JSON-RPC over a transport compatible with the Model Context Protocol. There are two primary ways to run the server and connect clients:

Run in HTTP mode to use the StreamableHTTP transport and connect via the MCP endpoint at /mcp (for example, http://localhost:8080/mcp). You can initialize a session, list available tools, and execute commands within that session.
Run in STDIO mode to work with traditional MCP clients directly in the terminal. This is the default mode if you start the server without the --http flag. In this mode, you interact through standard input/output streams without an HTTP layer.

Key capabilities you can leverage include persistent shell sessions that maintain state like the current working directory and environment variables, configurable command timeouts, and automatic forwarding of the DISPLAY variable for GUI applications started from within MCP.

How to install

Prerequisites you need on your host system before installing the MCP Terminal Server:

A Unix-like environment (macOS or Linux).
A Go toolchain or build utilities as required by the server’s build process.
Network access for pulling dependencies or building container images if used.

Install and run the server using the build and start steps shown below. These commands assume you are on a Unix-like system and have the necessary build tools available.

# Build the server
make build

# Run in HTTP mode with StreamableHTTP transport on port 8080
./mcp-terminal-server --http --port 8080

# Run in STDIO mode (default)
./mcp-terminal-server

Additional sections

Configuration and runtime behavior are designed to be practical and predictable. You can customize the shell used for command execution, set a default command timeout, and ensure GUI applications launched through MCP are displayed correctly by forwarding the DISPLAY variable.

Environment variables you can set to influence runtime behavior include MCP_COMMAND_TIMEOUT, MCP_SHELL, and DISPLAY. The server will forward DISPLAY to all executed commands so GUI apps open on the correct display.

Server endpoints in HTTP mode expose a StreamableHTTP transport at the path /mcp. You can initialize a session, list tools, and call tools to execute commands. All interactions follow the JSON-RPC 2.0 protocol and require a session identifier for authenticated requests.

Platform support includes macOS and Linux, with multi-architecture Docker images available for AMD64 and ARM64. Build and deployment workflows support local execution and containerized deployments for production environments.

Security considerations focus on non-root execution, resource limits, network isolation, and mandatory access controls like AppArmor or SELinux where available. Use a dedicated user account and restrict network exposure to minimize risk.

Available tools

execute_command

Executes a single command with a defined timeout and returns stdout/stderr and exit status.

persistent_shell

Maintains a persistent shell session across commands, preserving working directory and environment variables.

session_manager

Manages shell sessions, including listing and closing sessions.