MCP2TERM

Provides live, auditable access to a system shell with streaming outputs, remote file tools, and plugin extendability.

python

GitHub Stars

python

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "freddye1982-mcp2term": {
      "command": "mcp2term",
      "args": [
        "--transport",
        "stdio"
      ],
      "env": {
        "MCP2TERM_SHELL": "/bin/bash",
        "MCP2TERM_WORKDIR": ".",
        "MCP2TERM_EXTRA_ENV": "{}",
        "MCP2TERM_INHERIT_ENV": "true",
        "MCP2TERM_CONSOLE_ECHO": "true",
        "MCP2TERM_CHAT_TERMINAL": "unused",
        "MCP2TERM_COMMAND_TIMEOUT": "unlimited",
        "MCP2TERM_STREAM_CHUNK_SIZE": "65536",
        "MCP2TERM_LONG_COMMAND_NOTICE_DELAY": "2.0",
        "MCP2TERM_LONG_COMMAND_NOTICE_INTERVAL": "5.0"
      }
    }
  }
}

You can run a self-contained MCP server that safely exposes a shell with live command streaming, auditable metadata, and optional tunneling. This server lets you execute commands, stream stdout and stderr in real time, and manage files from remote tooling, all under a configurable environment.

How to use

To use the MCP server, start it with a transport that suits your environment, then connect with an MCP client to launch commands, stream outputs, and view structured results. You will issue commands through the client’s MCP tools, observe real-time stdout and stderr, and rely on the provided metadata for auditing and orchestration. You can also manage files remotely and extend behavior via plugins.

How to install

Prerequisites: ensure you have Python 3.12 or newer installed on your system.

Install the MCP server package in editable mode from your project directory:

pip install -e .

Run the server using a transport that suits your needs. For standard in-process streaming, use the stdio transport:

mcp2term --transport stdio

Additional sections

Configuration runs through environment variables. You can customize the shell, working directory, inheritance of the parent environment, and other runtime aspects.

Example environment settings you may adjust include the shell path, the base working directory, and plugin loading. For example, you can set the shell and enable or disable console mirroring according to your deployment needs.

The server includes built-in tooling for remote command execution and file manipulation. You can start commands through the MCP tooling, cancel running commands, stream input when needed, and perform file edits via the file tool. This enables automation and integration with orchestration systems.

Ngrok integration is enabled by default when using certain transports. Tunneling exposes the local MCP endpoint so remote clients can reach it without manual network setup. You can disable tunneling per invocation if desired.

Development and testing can be run with the project’s test suite to validate various execution paths and plugin interactions.

Configuration and runtime notes

Server behavior is influenced by environment variables that control the shell, working directory, environment inheritance, and plugin loading. You can adjust these to fit different deployment scenarios.

When using the streamable HTTP transport, the MCP endpoint is served from a specific path on your mounted URL and may be tunneled with a local ngrok agent if enabled. You can override behaviors using the provided environment variables.

Available tools

run_command

Executes a command with a configurable working directory, environment, and timeout, returning structured results including stdout, stderr, timing, and completion status.

cancel_command

Sends a signal to a running process identified by command_id and reports whether the signal was delivered.

send_stdin

Streams additional input to an interactive command, with an option to close the stdin pipe.

manage_file

Powers the file editing operations exposed by filetool, including patching, inserting, substituting, and more with various matching and escaping options.

Built by

VeilStrat

AI signals for GTM teams