Includes test suite integration for running parameterized tests with or without dependency stubbing
Runs on Python 3.12 or newer with a plugin architecture that exposes package functions, classes, and variables for extensions
Provides safe, auditable access to system shell commands with real-time streaming of stdout and stderr, configurable working directories, environment variables, and timeouts
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp2term run 'ls -la' in the current directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: Run Command MCP Server
pip install -e .The project targets Python 3.12 or newer.
ServerConfig reads settings from environment variables:
Variable | Description | Default |
| Shell executable used for commands. |
|
| Working directory for commands. | Current directory |
| When |
|
| JSON object merged into the command environment. |
|
| Comma-separated dotted module paths to load as plugins. | (none) |
| Default timeout in seconds for commands. | unlimited |
| Bytes read from stdout/stderr per chunk while streaming. |
|
| Seconds to wait before emitting long-running command notices. |
|
| Interval in seconds between long-running command notices. |
|
| Mirror commands and output to the server console ( |
|
| Set to | (unused) |
mcp2term --transport stdioChange --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.
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 autoPlugins 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.
Run the test suite with:
pytestTests are parameterised to run with or without dependency stubbing, ensuring full execution paths remain verified.
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 |
| Enable or disable automatic tunnel creation. |
|
| Comma-separated transports that should be tunnelled ( |
|
| Path to the |
|
| Base URL for the local ngrok API. |
|
| Optional ngrok region to target. | (none) |
| ngrok log level ( |
|
| JSON array of additional CLI arguments passed to ngrok. |
|
| JSON object merged into the ngrok process environment. |
|
| Seconds to wait for tunnel provisioning. |
|
| Seconds between tunnel status checks. |
|
| HTTP timeout for API calls. |
|
| Seconds to wait for ngrok to terminate gracefully. |
|
| Optional path to an ngrok configuration file. | (none) |
| Custom host bindings to request from ngrok. |
|
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.
Send a signal to a running command.
| Name | Required | Description | Default |
|---|---|---|---|
| command_id | Yes | ||
| signal_value | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'Send a signal' but doesn't clarify what the signal does (e.g., cancels, terminates, pauses) or any side effects (e.g., whether the command stops immediately, if data is lost, or if it requires specific permissions). For a tool that likely mutates command state, this lack of detail is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's action without unnecessary words. It's front-loaded with the core purpose ('Send a signal to a running command'), making it easy to parse quickly. Every word earns its place, adhering to best practices for conciseness in tool definitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (interacting with running commands, likely mutative), lack of annotations, 0% schema coverage, and no output schema details in the context, the description is incomplete. It doesn't cover behavioral traits, parameter meanings, or usage context, leaving an agent with insufficient information to invoke the tool correctly or understand its effects, despite the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning parameters are undocumented in the schema. The description adds no meaning beyond the schema: it doesn't explain what 'command_id' refers to (e.g., an identifier from 'run_command') or what 'signal_value' represents (e.g., numeric signals like SIGINT, string names, or null for default). With two parameters and no compensation in the description, this leaves key semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Send a signal') and target ('to a running command'), which clarifies the tool's basic purpose. However, it's vague about what 'signal' means (e.g., cancellation, interruption, or other signals) and doesn't distinguish it from sibling tools like 'run_command' or 'send_stdin', which might also interact with commands. This leaves room for ambiguity in understanding the exact function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., that a command must be running), exclusions, or how it differs from sibling tools like 'send_stdin' (which might send input) or 'manage_file' (unrelated). Without such context, an agent might struggle to select this tool appropriately in scenarios involving command management.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create, edit, and inspect files on the remote host including line-based operations.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| operation | Yes | ||
| content | No | ||
| pattern | No | ||
| line | No | ||
| start_line | No | ||
| end_line | No | ||
| encoding | No | utf-8 | |
| create_parents | No | ||
| overwrite | No | ||
| create_if_missing | No | ||
| escape_profile | No | auto | |
| follow_symlinks | No | ||
| use_regex | No | ||
| ignore_case | No | ||
| max_replacements | No | ||
| anchor | No | ||
| anchor_use_regex | No | ||
| anchor_ignore_case | No | ||
| anchor_after | No | ||
| anchor_occurrence | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions operations (create, edit, inspect), it doesn't address critical behavioral aspects: whether these operations are destructive, what permissions are required, how errors are handled, or what the output looks like. For a tool with 21 parameters and file system operations, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise - a single sentence that efficiently communicates the core functionality. Every word earns its place: 'Create, edit, and inspect' covers the main operations, 'files on the remote host' specifies the resource and context, and 'including line-based operations' adds important scope information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (21 parameters, file system operations), no annotations, and 0% schema description coverage, the description is insufficient. While an output schema exists, the description doesn't address critical context: mutation implications, error conditions, permission requirements, or how the numerous parameters interact. For such a complex tool, the single-sentence description leaves too many questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 21 parameters, the description provides minimal parameter context. It mentions 'line-based operations' which hints at parameters like 'line', 'start_line', and 'end_line', but doesn't explain how these parameters interact or what other parameters like 'escape_profile' or 'anchor' mean. The description doesn't compensate for the complete lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create, edit, and inspect files on the remote host including line-based operations.' It specifies the verb (create/edit/inspect), resource (files), and scope (remote host, line-based operations). However, it doesn't explicitly differentiate from sibling tools like run_command or send_stdin, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, constraints, or compare it to sibling tools like run_command for file operations. The phrase 'including line-based operations' hints at capabilities but doesn't establish clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a shell command with live stdout/stderr streaming.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| working_directory | No | ||
| environment | No | ||
| timeout | No | ||
| command_id | No | ||
| allocate_pty | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It mentions 'live stdout/stderr streaming' which adds behavioral context beyond the schema, but fails to disclose critical traits like security implications, permission requirements, potential destructive effects, rate limits, or error handling. For a shell execution tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Perfectly concise single sentence that front-loads the core purpose. Every word earns its place with no wasted text or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high complexity (shell execution with 6 parameters), no annotations, and 0% schema coverage, the description is inadequate. While an output schema exists, the description doesn't address security concerns, error cases, or parameter usage that are critical for this type of tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions no parameters at all, leaving all 6 parameters (command, working_directory, environment, timeout, command_id, allocate_pty) undocumented. The description adds no meaning beyond what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('execute') and resource ('shell command') with the specific behavior of 'live stdout/stderr streaming'. It distinguishes from sibling tools like cancel_command and send_stdin by focusing on execution rather than management or input. However, it doesn't explicitly differentiate from manage_file which might also involve execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like cancel_command or send_stdin. The description implies usage for executing shell commands with streaming output, but lacks context on prerequisites, when not to use it, or comparisons to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Forward input to a running command's stdin pipe.
| Name | Required | Description | Default |
|---|---|---|---|
| command_id | Yes | ||
| data | No | ||
| eof | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but doesn't describe what happens (e.g., whether input is buffered, if it blocks, error conditions like invalid command_id, or side effects). This leaves critical behavioral traits unspecified for a tool that interacts with running processes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and appropriately sized for the tool's complexity, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (interacting with running commands) and lack of annotations, the description is minimally adequate but incomplete. The presence of an output schema helps, but the description doesn't address behavioral nuances or parameter meanings, leaving gaps in understanding how to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but adds no parameter information. It doesn't explain what 'command_id' refers to, what 'data' should contain, or the meaning of 'eof' (likely 'end-of-file'). This leaves all three parameters semantically unclear beyond their schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Forward input') and target ('to a running command's stdin pipe'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'run_command' or 'cancel_command', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'run_command' or 'cancel_command'. It doesn't mention prerequisites (e.g., needing a running command), exclusions, or contextual triggers, leaving the agent to infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
cancel_commandmanage_filerun_commandsend_stdinEach tool has a clearly distinct purpose with no overlap: cancel_command stops processes, manage_file handles file operations, run_command executes commands, and send_stdin provides input to running commands. The boundaries are well-defined and unambiguous.
Three tools follow a consistent verb_noun pattern (cancel_command, run_command, send_stdin), but manage_file uses a more general verb that slightly deviates from the others. The naming is still highly readable and mostly consistent.
With 4 tools, this server is well-scoped for remote command and file management. Each tool earns its place by covering essential operations without bloat, making it appropriate for its purpose.
The toolset covers core remote execution workflows: running commands, managing files, and interacting with processes. A minor gap is the lack of a tool for listing or monitoring running processes, but agents can work around this using run_command with appropriate shell commands.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Execute PowerShell commands securely with controlled timeouts and input validation. Retrieve syste…
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Build Apps and run code in 30 languages — sandboxed, with persistent sessions for agent loops.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/FreddyE1982/mcp2term'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
