Skip to main content
Glama
shellserver

shellserver

by weezerzero

shellserver

A small Model Context Protocol (MCP) server built with the Python MCP SDK (FastMCP). It exposes one tool that runs shell commands on the machine where the server process runs.

Requirements

  • Python 3.14+ (see pyproject.toml)

  • uv for installing and running dependencies

Related MCP server: Shell MCP Server

Setup

Clone or copy this repository, then from the project root:

uv sync

Running the server

The server uses stdio transport (the default for FastMCP).

uv run python server.py

Do not pipe extra data to stdout from the server process; MCP uses stdout for JSON-RPC. Logging in server.py is directed to stderr.

Tool: terminal_tool

Parameter

Type

Required

Default

Description

command

string

yes

—

Shell command to run

cwd

string

no

—

Working directory for the subprocess

timeout_seconds

number

no

120

Seconds to wait before killing the process

The tool returns a single text block containing exit_code, stdout, and stderr. If the command exceeds the timeout, the process is terminated and the response indicates a timeout.

Connecting a client (example of running locally)

Point your MCP host at uv with this project as the working directory. Example configuration shape:

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

Adjust the key name and cwd to match your editor or client.

Security

This server executes arbitrary shell commands on the host. Anyone who can invoke MCP tools against this server effectively has shell access to that machine. Use only on trusted hosts, with trusted clients, and with clear understanding of the risk.

Available Tools

2 tools
benign_toolBenign ToolC

Download and return a fixed text file via curl.

Inputs: timeout_seconds. Returns: result

terminal_toolTerminal ToolB

Run a shell command on the host and return stdout, stderr, and exit code.

The command is executed with the system shell. Use only in trusted environments.

Inputs: command (required), cwd, timeout_seconds. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one downloads a fixed text file, the other executes shell commands. There is no ambiguity between them.

    Naming Consistency5/5

    Both tool names follow a consistent adjective_noun pattern in snake_case (benign_tool, terminal_tool), making them predictable and clear.

    Tool Count3/5

    With only 2 tools, the server feels thin for a shell execution server. While it covers the basic need, it is below the typical well-scoped range of 3-15 tools.

    Completeness4/5

    The core functionality of running shell commands is covered by terminal_tool. The presence of benign_tool as a fixed downloader is a minor addition; agents can work around the lack of other shell utilities like file listing.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    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
      -
    • A
      license
      A
      quality
      A
      maintenance
      A Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH. It supports password and key-based authentication, command timeouts, and sudo elevation for administrative tasks.
      15
      10,581 npm
      893
      MIT