Skip to main content
Glama

Shell Server

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

Python 3.13+ MCP Docker License uv


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

Related MCP server: MCP Terminal Tool Server

Quickstart

# 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)


Built with FastMCP and uv

Available Tools

1 tool
terminalA

Run a shell command and return its output.

Returns a single string containing stdout, and stderr when present. Non-zero exit codes are reported at the end of the output so the caller can detect failures without parsing exit status separately.

Inputs: command (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool available, there is no possibility of confusion or overlap with other tools. The single tool 'terminal' has a clear, unambiguous purpose.

    Naming Consistency3/5

    While there is no inconsistency across multiple tools (as there is only one), the name 'terminal' uses a noun format rather than the recommended verb_noun pattern (e.g., 'run_command'), making it less predictable and descriptive of the action performed.

    Tool Count2/5

    A single tool is explicitly considered 'too few' for most server scopes. A 'Shell Server' implying general shell access would reasonably be expected to support additional capabilities like session management, environment handling, or file operations, rather than just one-shot command execution.

    Completeness3/5

    The tool covers basic command execution with stdout/stderr/exit code handling, but notable gaps exist for a shell server, such as interactive session management, background process control, working directory specification, or environment variable manipulation.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      A server that enables AI assistants to execute terminal commands and retrieve outputs via the Model Context Protocol (MCP).
      3
      26
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      An MCP server that enables users to execute arbitrary shell commands on their local machine and receive the output. It provides a terminal tool for running system commands through MCP-compatible clients using the Python SDK.
      1
      -
    • A
      license
      B
      quality
      B
      maintenance
      A secure MCP server for shell operations, terminal management, and process control, enabling AI assistants to safely execute commands and manage interactive sessions.
      13
      158 npm
      6
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      MCP server that provides AI access to a local terminal, enabling command execution, directory navigation, and system operations with persistent session state.
      5
      1
      -