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

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.