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

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

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.