MCP Terminal Server

You can run a secure terminal execution service that integrates with the Model Context Protocol (MCP). It lets you execute restricted shell commands, capture output, and enforce security and resource limits, all through MCP-compatible clients.

How to use

Connect an MCP client to the terminal server and request execution of allowed commands. You specify which commands are permitted, and the server streams stdout/stderr as the command runs. You can rely on timeouts to prevent hanging processes and output size limits to protect memory usage. Expect a structured result that includes the command’s exit code, collected output, and timing information.

How to install

Prerequisites: You need Python and a compatible runtime toolchain installed on your system.

Step 1: Install the runtime helper for running MCP servers locally.

Step 2: Create and activate a virtual environment for isolation.

Step 3: Install development dependencies to enable running and testing the MCP server.

Step 4: Start the server in a testing mode using the MCP Inspector to verify behavior with a set of allowed commands.

Additional configuration and notes

Testing and verification use an MCP Inspector tool to exercise the server with a set of allowed commands such as python, pip, git, ls, and cd. The inspector runs a test command against the server to ensure command validation, timeout handling, and output streaming work as expected.

Claude Desktop can be configured to access the MCP server. The configuration creates a terminal entry that launches a local MCP client with a predefined set of allowed commands and limits. Below is a representative configuration snippet you can adapt.

{
  "mcpServers": {
    "terminal": {
      "command": "uv",
      "args": [
        "pip",
        "run",
        "mcp-terminal",
        "--allowed-commands",
        "python,pip,git,ls,cd",
        "--timeout-ms",
        "30000",
        "--max-output-size",
        "1048576"
      ]
    }
  }
}

Tools and capabilities you get

The server exposes a primary capability to execute terminal commands under strict control. It advertises this capability to MCP clients along with parameter and return structure so you can integrate command execution into your workflows.

Troubleshooting and tips

If a command is blocked, verify that it is included in the allowed commands list. Adjust timeouts or maximum output size if you encounter timeouts or memory-related errors. Check execution logs for failed commands and review the security controls to ensure no disallowed operators or injection attempts are allowed.

Security and runtime considerations

Enforce a conservative set of allowed commands in production. Use timeouts to prevent long-running processes and limit the amount of data returned to prevent memory exhaustion. Monitor logs to detect unusual activity and ensure proper handling of errors across all failure scenarios.

Examples and quick-start commands

# Start the MCP Inspector against the server via stdio interface (example usage)
npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd"

Available tools

execute

Execute a terminal command under MCP control and receive stdout, stderr, exitCode, and timing information.

capabilitiesAdvertisement

Advertise supported MCP capabilities for the terminal execution service, including parameters and return structure.

stream_output

Stream command output to the client as it is produced, enabling interactive-like feedback within a single MCP request/response cycle.