Shell

You can run a dedicated MCP server that exposes a terminal tool to execute shell commands remotely. This enables you to run shell operations from an MCP client, receive output, and control where commands execute from within a defined working directory and with a safety timeout.

How to use

To use this server with an MCP client, start the local stdio server and connect your client to it. By default, the server communicates over stdio, which is suitable for MCP clients that run locally.

Start the server using the simple runtime command. The server runs as a Python process and serves the terminal tool named terminal.

When you call the terminal tool, you specify the shell command to run, and you may optionally provide a working_directory and a timeout. The server handles argument parsing safely and captures both standard output and standard error. If a command runs longer than the timeout, it will be terminated.

Examples of how you might invoke the tool from your MCP client (conceptual, not raw RPC): you request the terminal tool with a command like ls -la, optionally in a specific directory such as /tmp, and with a timeout like 10 seconds.

How to install

Prerequisites you need on your system include Python and a runtime tool for managing your MCP server. You can install dependencies using the recommended runtime tool or directly with Python’s package manager.

Install dependencies using the recommended runner, or install the package in editable mode with Python.

Then run the server directly with Python.

You can configure your MCP client to connect to this local server using the provided configuration examples.

Configuration and examples

Here are example client configurations that show how to connect to the local server. These are focused on MCP client integration and assume the server is accessible via stdio.

{
  "mcpServers": {
    "shellserver": {
      "command": "python",
      "args": ["/path/to/shellserver/server.py"]
    }
  }
}

You can adapt the path to the actual location of your server script when configuring your MCP client.

Security considerations

⚠️ Warning: This server executes arbitrary shell commands. Use in trusted environments and avoid exposing it to untrusted users. Commands run with the privileges of the user invoking the server and are subject to system limitations.

The server parses arguments safely and imposes a timeout to prevent long-running commands. Consider running the server in a restricted environment or container for production deployments.

Tool and usage notes

Tool available: terminal accepts a command to execute, an optional working_directory, and an optional timeout. You can reuse this tool to script common shell tasks from your MCP client.

Development note: This server is built using MCP Python SDK and FastMCP for simplified server creation.

Available tools

terminal

Executes a shell command provided by the client, optionally within a specified working directory, with an adjustable timeout. Returns command output and status.