Shell Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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
terminaltool that runs any shell commandStdout + 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.pyWith Docker
# Build the image
docker build -t shellserver .
# Run the container
docker run --rm -i shellserverOr pull directly from Docker Hub:
docker run --rm -i yourusername/shellserver:latestMCP 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 |
|
| 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: 1Project Structure
shellserver/
├── server.py # MCP server implementation
├── pyproject.toml # Project metadata & dependencies
├── uv.lock # Locked dependencies
├── Dockerfile # Container build file
└── README.mdRequirements
Python 3.13+
uv (for local development)
Docker (for containerized usage)
Available Tools
1 toolterminalA
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
Scored across 1 tool
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.
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.
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.
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
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Termalin's hosted MCP server. Claude, ChatGPT or any MCP client runs commands, moves files over SFTP, queries databases and reads server metrics and monitoring alerts on your servers, keylessly through Termalin Connectors: no SSH key is handed over and no inbound port is opened. Per-host command policy and an audit log. Needs a termal.in Pro or Team account (new accounts start with a 14-day Pro trial).
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseCqualityDmaintenanceA server that enables AI assistants to execute terminal commands and retrieve outputs via the Model Context Protocol (MCP).326MIT
- FlicenseBqualityDmaintenanceAn 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-
- AlicenseBqualityBmaintenanceA secure MCP server for shell operations, terminal management, and process control, enabling AI assistants to safely execute commands and manage interactive sessions.13158 npm6MIT
- FlicenseAqualityBmaintenanceMCP server that provides AI access to a local terminal, enabling command execution, directory navigation, and system operations with persistent session state.51-