mcp2term

An implementation of a Model Context Protocol (MCP) server that grants safe, auditable access to a system shell. The server streams stdout and stderr in real time while capturing rich metadata for plugins and downstream consumers.

Features

Full command execution with configurable shell, working directory, environment variables, and timeouts.
Live streaming of stdout and stderr via MCP log notifications so clients observe progress as it happens.
Robust chunked streaming that handles large stdout/stderr volumes without blocking or truncation.
Plugin architecture that exposes every function, class, and variable defined in the package, enabling extensions to observe command lifecycles or inject custom behaviour.
Remote file management tools allowing safe file creation, printing, line-range replacement, exact line lookups, and unified diff patching via the manage_file tool and filetool client command.
Automatic ngrok tunneling so HTTP transports are reachable without additional manual setup.
Typed lifespan context shared with MCP tools for dependency access and lifecycle management.
Structured tool responses including timing information to make results easy for agents to consume.
Console mirroring so operators always see the command stream, stdout, and stderr on the hosting terminal by default.
Automatic launch-directory export that prepends the directory the server was started from to PYTHONPATH so Python tooling invoked through run_command can immediately resolve local packages.

Installation

pip install -e .

The project targets Python 3.12 or newer.

Configuration

ServerConfig reads settings from environment variables:

Variable	Description	Default
`MCP2TERM_SHELL`	Shell executable used for commands.	`/bin/bash`
`MCP2TERM_WORKDIR`	Working directory for commands.	Current directory
`MCP2TERM_INHERIT_ENV`	When `true`, inherit the parent environment.	`true`
`MCP2TERM_EXTRA_ENV`	JSON object merged into the command environment.	`{}`
`MCP2TERM_PLUGINS`	Comma-separated dotted module paths to load as plugins.	(none)
`MCP2TERM_COMMAND_TIMEOUT`	Default timeout in seconds for commands.	unlimited
`MCP2TERM_STREAM_CHUNK_SIZE`	Bytes read from stdout/stderr per chunk while streaming.	`65536`
`MCP2TERM_LONG_COMMAND_NOTICE_DELAY`	Seconds to wait before emitting long-running command notices.	`2.0`
`MCP2TERM_LONG_COMMAND_NOTICE_INTERVAL`	Interval in seconds between long-running command notices.	`5.0`
`MCP2TERM_CONSOLE_ECHO`	Mirror commands and output to the server console (`true`/`false`).	`true`
`MCP2TERM_CHAT_TERMINAL`	Set to `disabled` to suppress the console-integrated messaging bridge. Legacy values are accepted but ignored.	(unused)

Running the server

mcp2term --transport stdio

Change --transport to sse or streamable-http to use the corresponding MCP transports. --log-level controls verbosity and --mount-path overrides the HTTP mount location when relevant.

While the server is running it mirrors every executed command, stdout chunk, and stderr chunk to the hosting console. Set MCP2TERM_CONSOLE_ECHO=false to suppress the mirroring when embedding the server into log-sensitive environments.

When running with the streamable-http transport the MCP endpoint is served from the /mcp path (or --mount-path plus /mcp when a custom mount is provided). The CLI prints the fully qualified URL, including the /mcp suffix, to make tunnelling targets such as ngrok easy to copy.

MCP tools

The server exposes two tools for remote command management:

run_command(command: str, working_directory: Optional[str], environment: Optional[dict[str, str]], timeout: Optional[float]], command_id: Optional[str])

The tool returns structured JSON containing:

command_id: unique identifier assigned to the invocation
command: executed command string
working_directory: resolved working directory
return_code: process exit code (non-zero for failure)
stdout / stderr: aggregated output
started_at / finished_at: ISO 8601 timestamps
duration: execution duration in seconds
timed_out: boolean flag indicating whether a timeout occurred

While a command runs the server emits stdout and stderr chunks as MCP log messages, preserving ordering through asynchronous streaming. Clients can reuse command_id values when making follow-up requests.

cancel_command(command_id: str, signal_value: Optional[str | int])

Sending cancel_command forwards a signal (defaulting to SIGINT) to the running process identified by command_id. The response includes the numeric signal, its symbolic signal_name, and a delivered flag confirming whether the process was still active when the signal was sent.

send_stdin(command_id: str, data: Optional[str], eof: bool = False)

Use send_stdin to stream additional input to an interactive command. The tool accepts optional text payloads and an eof flag that closes the stdin pipe once all required data has been delivered. The response reports whether the input was accepted so clients can retry or surface helpful diagnostics.

manage_file(path: str, *, operation: str, content: Optional[str] = None, pattern: Optional[str] = None, line: Optional[int] = None, start_line: Optional[int] = None, end_line: Optional[int] = None, encoding: str = "utf-8", create_parents: bool = False, overwrite: bool = False, create_if_missing: bool = True, escape_profile: str = "auto", follow_symlinks: bool = True, use_regex: bool = False, ignore_case: bool = False, max_replacements: Optional[int] = None, anchor: Optional[str] = None, anchor_use_regex: bool = False, anchor_ignore_case: bool = False, anchor_after: bool = False, anchor_occurrence: Optional[int] = None)

manage_file powers the filetool client command and exposes a broad suite of line-aware editing operations. The escape_profile parameter controls how inline --content payloads are normalised before they reach the server:

auto (default) mirrors the original behaviour and expands \n, \t, \r, and \0 sequences when the payload would otherwise be a single line.
none disables all inline decoding so payloads arrive exactly as typed, perfect for binary-friendly workflows or when backslashes carry semantic meaning.
Additional profiles can be registered by extensions to enforce organisation-specific escaping rules. The selected profile is forwarded to plugins via the FileOperationEvent payload so observability tooling can respond appropriately.

Recent updates add top-of-file editing and pattern-driven substitutions to the toolbox:

prepend injects content at the start of a file and respects --create-if-missing so you can bootstrap brand new files with headers in a single command.
insert now accepts literal or regex anchors via --anchor, --anchor-after, --anchor-ignore-case, and --anchor-occurrence, making it easy to land changes relative to sentinel text without counting lines.
substitute --pattern PATTERN --content TEXT performs literal or regex-based replacements while streaming structured metadata (matched pattern, replacement counts, and flags such as --ignore-case or --max-replacements) back to the caller.

Example usages:

# Create a multi-line file from a single-shell command using the default profile.
filetool write docs/roadmap.txt --content 'phase-one\\nphase-two\\nphase-three'

# Append literal escape sequences without rewriting them by selecting the "none" profile.
filetool append docs/roadmap.txt --content 'literal\\nvalue' --escape-profile none

# Use stdin for bulk updates while still labelling the request for plugins.
cat release.diff | filetool patch docs/roadmap.txt --stdin --escape-profile auto

Plugins

Plugins implement the PluginProtocol (via a module-level PLUGIN object) and can register CommandStreamListener instances to observe command lifecycle events. When the server starts it loads modules listed in MCP2TERM_PLUGINS, exposing the entire mcp2term namespace through the plugin registry for inspection or extension.

A minimal plugin skeleton:

from dataclasses import dataclass

from mcp2term.plugin import CommandStreamListener, PluginProtocol, PluginRegistry

@dataclass
class EchoListener(CommandStreamListener):
    async def on_command_stdout(self, event):
        print(event.data, end="")

    async def on_command_start(self, event):
        print(f"Starting: {event.request.command}")

    async def on_command_stderr(self, event):
        print(f"[stderr] {event.data}", end="")

    async def on_command_complete(self, event):
        print(f"Finished with {event.return_code}")


class ShellEchoPlugin(PluginProtocol):
    name = "shell-echo"
    version = "1.0.0"

    def activate(self, registry: PluginRegistry):
        registry.register_command_listener(EchoListener())

        class AuditListener:
            async def on_file_operation(self, event):
                print(f"{event.operation} {event.path}: {event.result.message}")

        registry.register_file_operation_listener(AuditListener())


PLUGIN = ShellEchoPlugin()

Listeners registered through register_file_operation_listener receive FileOperationEvent instances containing the original request arguments, the resolved path, the FileOperationResult, and any warning emitted during processing. This makes it straightforward to build auditing, notification, or synchronization plugins that react to remote edits in real time without modifying the core server.

Development

Run the test suite with:

pytest

Tests are parameterised to run with or without dependency stubbing, ensuring full execution paths remain verified.

Ngrok integration

By default mcp2term opens an ngrok tunnel whenever you run the server with the sse or streamable-http transports. The tunnel exposes the local HTTP endpoint using the ngrok agent that must already be authenticated (for example via ngrok config add-authtoken). Unless overridden, the server now requests the reserved domain alpaca-model-easily.ngrok-free.app so clients always receive a predictable hostname.

Control the integration with the following environment variables:

Variable	Description	Default
`MCP2TERM_NGROK_ENABLE`	Enable or disable automatic tunnel creation.	`true`
`MCP2TERM_NGROK_TRANSPORTS`	Comma-separated transports that should be tunnelled (`stdio`, `sse`, `streamable-http`).	`sse,streamable-http`
`MCP2TERM_NGROK_BIN`	Path to the `ngrok` executable.	`ngrok`
`MCP2TERM_NGROK_API_URL`	Base URL for the local ngrok API.	`http://127.0.0.1:4040`
`MCP2TERM_NGROK_REGION`	Optional ngrok region to target.	(none)
`MCP2TERM_NGROK_LOG_LEVEL`	ngrok log level (`debug`, `info`, `warn`, `error`).	`info`
`MCP2TERM_NGROK_EXTRA_ARGS`	JSON array of additional CLI arguments passed to ngrok.	`[]`
`MCP2TERM_NGROK_ENV`	JSON object merged into the ngrok process environment.	`{}`
`MCP2TERM_NGROK_START_TIMEOUT`	Seconds to wait for tunnel provisioning.	`15`
`MCP2TERM_NGROK_POLL_INTERVAL`	Seconds between tunnel status checks.	`0.5`
`MCP2TERM_NGROK_REQUEST_TIMEOUT`	HTTP timeout for API calls.	`5`
`MCP2TERM_NGROK_SHUTDOWN_TIMEOUT`	Seconds to wait for ngrok to terminate gracefully.	`5`
`MCP2TERM_NGROK_CONFIG`	Optional path to an ngrok configuration file.	(none)
`MCP2TERM_NGROK_HOSTNAME` / `MCP2TERM_NGROK_DOMAIN` / `MCP2TERM_NGROK_EDGE`	Custom host bindings to request from ngrok.	`alpaca-model-easily.ngrok-free.app` for domain

Use the --disable-ngrok flag when running mcp2term to opt out of tunneling for a single invocation. The configuration also records the directory where the server process was launched and exports it to PYTHONPATH. This mirrors running export PYTHONPATH=$(pwd) before starting the server so that any Python code executed via run_command inherits the same module search path even when the working directory is overridden.