Skip to main content
Glama

Shell Server - MCP Terminal Tool

A simple MCP (Model Context Protocol) server that exposes a terminal tool for executing shell commands.

Features

  • Execute shell commands via MCP protocol

  • Support for custom working directories

  • Configurable timeout for command execution

  • Safe command parsing using shlex

  • Proper error handling and output capture

Related MCP server: Shell MCP Server

Installation

Install dependencies using uv (recommended) or pip:

# Using uv
uv sync

# Or using pip
pip install -e .

Usage

Running the Server

Run the server directly:

python server.py

The server uses stdio transport by default, which is suitable for MCP clients like Claude Desktop or Cursor.

MCP Client Configuration

To use this server with an MCP client, add it to your client configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Cursor (similar configuration):

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

Tool Usage

The server exposes a single tool called terminal with the following parameters:

  • command (required): The shell command to execute (e.g., "ls -la", "pwd", "echo hello")

  • working_directory (optional): The working directory to run the command in

  • timeout (optional): Timeout in seconds (default: 30.0)

Example Tool Calls

{
  "name": "terminal",
  "arguments": {
    "command": "ls -la"
  }
}
{
  "name": "terminal",
  "arguments": {
    "command": "pwd",
    "working_directory": "/tmp"
  }
}
{
  "name": "terminal",
  "arguments": {
    "command": "echo 'Hello, World!'",
    "timeout": 10.0
  }
}

Security Considerations

⚠️ Warning: This server allows execution of arbitrary shell commands. Use with caution:

  • The server executes commands in the context of the user running it

  • Commands are parsed using shlex to handle quoted arguments safely

  • A timeout is enforced to prevent long-running commands

  • Consider running the server in a restricted environment or container for production use

Development

The server is built using:

License

MIT

Available Tools

1 tool
terminalB
Execute a shell command and return the output.

Args:
    command: The shell command to execute (e.g., "ls -la", "pwd", "echo hello")
    working_directory: Optional working directory to run the command in. 
                      If not provided, uses current directory.
    timeout: Optional timeout in seconds (default: 30.0)
    ctx: MCP context (automatically provided)

Returns:
    A string containing the command output, or an error message if execution fails.

Inputs: command (required), timeout, working_directory. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of confusing it with another. Its purpose—execute a shell command—is explicit and unambiguous.

    Naming Consistency4/5

    A single tool cannot exhibit inconsistency, and 'terminal' is clear and readable. It is a noun rather than a verb_noun action name, so it does not fully follow the ideal convention.

    Tool Count4/5

    A shell server naturally needs only one general-purpose execution tool, so the count is well-scoped rather than bloated. It is on the thin side, but additional tools would likely be redundant wrappers.

    Completeness4/5

    Because arbitrary shell commands can cover file operations, process control, and environment inspection, the surface is functionally broad. Minor gaps exist around streaming output, session persistence, and structured error handling, but these are workable via shell.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      A secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.
      1
      202
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that allows LLMs to execute shell commands and receive their output in a controlled manner.
      7
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables LLM applications to safely execute shell commands with error handling and timeout settings.
      1
      -
    • F
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that exposes a tool to execute shell commands on the host machine, with customizable working directory and timeout.
      2
      -