<div align="center">

Shell Server

A lightweight MCP server that gives AI assistants access to your terminal.

---

Run shell commands through the Model Context Protocol — connect any MCP-compatible AI client to your system's terminal.

</div>

Features

• Single tool, full power — exposes a terminal tool that runs any shell command
• Stdout + stderr — returns combined output with clear labeling
• Timeout protection — commands are capped at 30 seconds
• Error reporting — non-zero exit codes are surfaced automatically
• Stdio transport — works with any MCP client out of the box

Quickstart

With uv (recommended)

# Clone the repo
git clone https://github.com/joandiazcapell/shellserver.git
cd shellserver

# Install dependencies and run
uv sync
uv run server.py

With Docker

# Build the image
docker build -t shellserver .

# Run the container
docker run --rm -i shellserver

Or pull directly from Docker Hub:

docker run --rm -i yourusername/shellserver:latest

MCP Client Configuration

Add this to your MCP client config to connect:

Local (uv)

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

Docker

{
  "mcpServers": {
    "shell": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "shellserver"]
    }
  }
}

Tool Reference

terminal

Run a shell command and return its output.

Parameter	Type	Description
command	string	The shell command to execute

Returns — stdout, stderr (if any), and exit code (if non-zero).

> terminal("echo hello world")
hello world

> terminal("ls nonexistent")
STDERR:
ls: nonexistent: No such file or directory
Exit code: 1

Project Structure

shellserver/
├── server.py          # MCP server implementation
├── pyproject.toml     # Project metadata & dependencies
├── uv.lock            # Locked dependencies
├── Dockerfile         # Container build file
└── README.md

Requirements

• Python 3.13+
• uv (for local development)
• Docker (for containerized usage)

---

<div align="center">

Built with FastMCP and uv

</div>