Skip to main content
Glama
joandiazcapell

Shell Server

by joandiazcapell
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

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)

Built with FastMCP and uv

Install Server
A
security – no known vulnerabilities
F
license - not found
A
quality - A tier

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/joandiazcapell/shellserver'

If you have feedback or need assistance with the MCP directory API, please join our Discord server