How do I use Shell Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Shell Server list all files in my current directory" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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.

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