Shell MCP Server

Shell MCP Server

Simple Model Context Protocol (MCP) server that exposes a single terminal tool for running shell commands.

Prerequisites

• Python 3.11+
• uv or pip

Installation

uv sync
# or
pip install -e .

Usage

Run the server over stdio:

python main.py

The server registers a terminal tool. Invoke it with an object shaped like:

{
  "command": "echo hello"
}

Command output is returned as MCP TextContent. Errors are surfaced with a prefixed Error: message.

Resource

This server exposes a resource:

• ID: mcpreadme://desktop
• Returns the contents of mcpreadme.md resolved from OneDrive Desktop.

Resolution order:

• $OneDrive/Desktop/mcpreadme.md
• ~/OneDrive/Desktop/mcpreadme.md
• ~/Desktop/mcpreadme.md

If the file is missing or unreadable, a textual error message is returned.

Docker

Build and run with uv inside the container (per uv Docker guide):

docker build -t shellserver .
docker run --rm -it shellserver

This image installs uv from the official image and uses:

• Dependency caching layers via uv sync --no-install-project
• Final run command equivalent to local: uv run main.py

Reference: uv Docker integration docs: Installing a project