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

Related MCP server: MCP Terminal Tool Server

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

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe shell command to execute. Runs via /bin/sh -c on Unix or cmd /c on Windows. Pipes, redirects, and shell built-ins are supported. Commands time out after 30 seconds.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It transparently explains output formatting (stdout/stderr combined, exit codes appended) but omits safety warnings, destructive potential, or execution boundaries that would be critical for an arbitrary shell execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly constructed sentences with no wasted words. The description front-loads the core action, followed by output structure specifics and error-handling behavior. Every sentence provides distinct value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple single-parameter input and implied output schema, the description adequately covers return value behavior. Minor gap: lacks safety warnings expected for shell execution tools, though the mechanics are fully documented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, documenting the command parameter, timeout behavior, and shell environments. The description focuses on output behavior rather than parameter semantics, meeting the baseline expectation without adding redundant param details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Run') and resource ('shell command'), clearly stating the tool executes commands and returns output. Without sibling tools, no differentiation is required, and the purpose is immediately obvious.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit 'when to use' guidance is provided, though the description explains how to interpret results (non-zero exit codes appended to output). This provides implicit usage guidance for error detection but lacks context about when shell execution is appropriate versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.1.0
    • First observedterminal
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0
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.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Related MCP Connectors

Related MCP Servers

  • MCP Terminal

    sichang824
    A
    license
    C
    quality
    C
    maintenance
    A server that enables AI assistants to execute terminal commands and retrieve outputs via the Model Context Protocol (MCP).
    3
    27
    MIT

  • MCP Terminal Tool Server

    gkgaurav31
    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
    -

  • MCP Shell Server

    mako10k
    A
    license
    B
    quality
    A
    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
    204
    6
    MIT

  • mcp-ia-web

    brigsd
    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
    -

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